Diagnosing Core‑JS Polyfill Issues in Modern JavaScript Builds

Common Core‑JS Problems

When targeting older browsers or using a build tool that transpiles modern syntax, developers often run into subtle polyfill issues. Core‑JS is the de‑facto polyfill library, but mis‑configurations can cause runtime errors, oversized bundles, or duplicate code. This guide walks through the most frequent conditions, how to detect them, and how to fix them in a reproducible way.

Diagnostic Table

Condition	Cause	Check	Fix	Escalation
ReferenceError: Symbol is not defined (IE11)	core‑js polyfill for Symbol not imported; preset‑env mis‑configured or core-js <3	Inspect bundle for core-js/modules/es.symbol import; run npm ls core-js	Import core-js/es/symbol or upgrade to core-js@3 and configure @babel/preset-env with useBuiltIns: 'usage' and corejs: 3	Open issue with minimal reproduction if error persists after config
Bundle size >200 KB after adding core-js imports	Importing entire core-js or using useBuiltIns: 'entry' without pruning	Run webpack-bundle-analyzer or source-map-explorer and look for core-js/modules/* entries	Switch to useBuiltIns: 'usage' or import only needed modules (e.g., core-js/es/array/map)	Consider core-js-pure or lazy‑loading polyfills if size remains high
Duplicate polyfill warnings (e.g., core-js/modules/es.promise already loaded)	Multiple core-js versions (v2 & v3) or both entry and usage modes	Run npm ls core-js; inspect bundle for duplicate paths	Align all dependencies to a single core-js version (preferably 3) and use only one mode	Check transitive dependencies and enforce via resolutions field if duplication persists
Runtime error regeneratorRuntime is not defined with async/await	Missing regenerator runtime polyfill; core-js does not provide it	Verify regenerator-runtime/runtime import in entry point or plugin configuration	Add import 'regenerator-runtime/runtime' or configure @babel/plugin-transform-runtime	Ensure target browsers include ES2017+; otherwise exclude old browsers via browserslist
Build fails: Cannot find module 'core-js/modules/es.symbol' after upgrade to core-js@3	Code uses core-js@2 import style (e.g., core-js/es6/symbol)	Search codebase for core-js/es6/ or core-js/library/	Migrate imports to core-js/es/ or core-js/stable/ or install core-js@2 with aliasing	Run a codemod (e.g., jscodeshift) if many files are affected

Step‑by‑Step Checks

1. Verify core-js version

   npm ls core-js
   # Expected output: core-js@3.x.x (no duplicate entries)

2. Check Babel configuration

   cat .babelrc
   # Look for:
   # {
   #   "presets": [
   #     ["@babel/preset-env", {
   #       "useBuiltIns": "usage",
   #       "corejs": 3
   #     }]
   #   ]
   # }
   # If using "entry", ensure you import "core-js/stable" and "regenerator-runtime/runtime" once.
   

3. Inspect bundle modules

   npx webpack-bundle-analyzer
   # Navigate to modules tree and confirm only the needed core-js modules appear.
   

4. Run the app in the target browser

   # Open IE11 or Edge (legacy) and check console for ReferenceErrors.
   # If no errors, polyfills are loaded.
   

Fixes Tied to Findings

• Missing Symbol polyfill – add import 'core-js/es/symbol' to the entry file or rely on useBuiltIns: 'usage'.
• Bundle bloat – switch to useBuiltIns: 'usage' or import modules individually.
• Duplicate polyfills – ensure a single core-js version and choose either entry or usage mode.
• Missing regeneratorRuntime – add import 'regenerator-runtime/runtime' or configure @babel/plugin-transform-runtime.
• Import path errors after core-js@3 upgrade – replace core-js/es6/* with core-js/es/* or core-js/stable/*.

Practical Example: Fixing Symbol ReferenceError

Suppose you see ReferenceError: Symbol is not defined in IE11 after adding core-js@3 to your project. Follow these steps:

1. Check current Babel config

   cat .babelrc
   # If "useBuiltIns" is "entry", ensure you have:
   # import 'core-js/stable';
   # import 'regenerator-runtime/runtime';
   # If "usage", remove the entry imports.
   

2. Verify core-js presence in bundle

   npx webpack-bundle-analyzer
   # Look for "core-js/modules/es.symbol.js".
   

3. If the module is missing, add an explicit import in src/index.js:

   import 'core-js/es/symbol';
   

4. Rebuild and run in IE11 – the error should be gone.

After applying the fix, run npm ls core-js again to confirm no duplicate versions remain.

Escalation Criteria

• If the error persists after following the above steps, create a minimal reproduction repository and open an issue on the relevant library (e.g., @babel/preset-env or core-js).
• For persistent bundle bloat, profile the bundle with source-map-explorer and consider replacing core-js with core-js-pure or dynamic imports.
• If duplicate polyfills cannot be eliminated due to transitive dependencies, add a resolutions field in package.json to force a single core-js version.

Limitations

• Core‑JS v3 is the current stable release; older projects may still rely on v2, which requires separate handling.
• Some build tools (e.g., Rollup) may need additional plugins to honor useBuiltIns correctly.
• Targeting environments that do not support Symbol may still require runtime checks in code.