Diagnosing CoreJS 3 Polyfill Integration Issues in Babel Builds

Problem Overview

When using @babel/preset-env with CoreJS 3, developers often see runtime errors, unexpectedly large bundles, or duplicate polyfill code. These symptoms usually trace back to useBuiltIns configuration, version mismatches, or an overly permissive browserslist. This guide maps common conditions to their causes, provides ordered checks, and ties fixes to each finding.

Diagnostic Table

Condition	Typical Symptom	Possible Cause
Runtime error: Promise is not defined or Symbol.iterator missing	Missing polyfill at runtime	useBuiltIns not set to "entry" or CoreJS version mismatch between Babel config and package.json
Bundle size >200 KB gzipped for polyfills alone	Excessive bundle size	useBuiltIns: "usage" with loose browserslist or importing the entire core-js instead of per‑feature polyfills
Duplicate polyfill code (e.g., Promise appears twice)	Same polyfill module duplicated in bundle	Both useBuiltIns: "usage" and manual core-js imports, or multiple entry points each importing polyfills
Native APIs behave unexpectedly (e.g., custom Promise breaks)	Native API overridden incorrectly	Enabling the proposals flag may polyfill stage‑3 features that differ from the final spec; test whether the polyfill is needed
TypeScript error: Property 'flat' does not exist on type 'Array'	Missing global type definitions	TypeScript lib setting does not include the polyfilled features; core-js provides its own types, no extra @types/core-js required
Build fails in IE11 with syntax errors	Polyfill code not transpiled for IE11	Verify that the chosen core-js version includes IE11 polyfills; as of core-js 3.x, IE11 support is still present, but check the changelog for any version‑specific changes

Step‑by‑Step Checks

1. Validate Babel configuration

   Ensure @babel/preset-env has explicit CoreJS settings. Example:

   {
     "presets": [
       ["@babel/preset-env", {
         "useBuiltIns": "entry",
         "corejs": { "version": 3, "proposals": false }
       }],
       "@babel/preset-react"
     ]
   }

   Run npx browserslist --debug (requires Node.js and access to the project) to confirm that your browserslist matches the intended target matrix. A loose target such as ">0.25%" can pull many unnecessary polyfills.

   Where to run: project root. Permissions: read access to package.json and browserslist file. Risk: none.

2. Check entry‑point polyfill imports

   When using useBuiltIns: "entry", add these imports at the very top of the main entry file (e.g., src/index.js):

   import 'core-js/stable';
   import 'regenerator-runtime/runtime';

   Missing these imports leads to runtime errors for features like Promise or async/await.

   Where to edit: application entry point. Permissions: write access to the file. Risk: none.

3. Audit the bundle for duplicate polyfills

   Use a bundle‑visualisation tool such as webpack-bundle-analyzer, rollup-plugin-visualizer, or the built‑in analyzer of your bundler. Look for repeated paths like core-js/modules/_promise.js.

   If duplicates exist:

   • Ensure only one entry point imports core-js/stable and regenerator-runtime/runtime.
   • When useBuiltIns: "usage" is active, remove any manual import 'core-js/...' statements.

   Where to run: in the project after a production build. Permissions: read access to build output. Risk: none.

4. Verify TypeScript global types

   Add the relevant lib entries to tsconfig.json to match the features you polyfill. Example for Array.prototype.flat (ES2019):

   {
     "compilerOptions": {
       "lib": ["es2019.array", "dom"],
       "types": []
     }
   }

   Because core-js ships its own type definitions, installing @types/core-js is unnecessary and deprecated.

   Run npx tsc --noEmit to confirm no type errors remain.

   Where to run: project root. Permissions: read access to tsconfig.json. Risk: none.

5. Check IE11 compatibility

   If IE11 is a target, verify that your core-js version includes the needed polyfills. As of the 3.x line, IE11 support is retained, but consult the core-js changelog for any version‑specific notes.

   Run npm list core-js to see the installed version.

   Where to run: project root. Permissions: read access to package-lock.json or yarn.lock. Risk: none.

Concrete Example: Missing Promise Polyfill

Suppose a production build fails in Chrome 49 with the error Promise is not defined. The browserslist includes chrome 49, but the bundle contains no Promise polyfill.

Root cause: useBuiltIns is set to "usage" and the entry file does not import core-js/stable.

Fix: Switch to "entry" and add the imports:

// src/index.js
import 'core-js/stable';
import 'regenerator-runtime/runtime';

// rest of the application

Rebuild and test in Chrome 49; the error should disappear.

Limitations & Escalation

• The proposals flag includes stage‑3 features that may still change; enable it only when a specific proposal is required and test its behavior in target browsers.
• When using useBuiltIns: "usage", a very broad browserslist can inflate bundle size. Prefer explicit targets such as last 2 Chrome versions, Firefox ESR, Safari 14+.
• If duplicate polyfills persist after removing manual imports and ensuring a single entry point, inspect the build cache or verify that all entry points (e.g., main app and web workers) share the same polyfill imports.
• Babel 7.20+ changed the default detection of the corejs version; always specify corejs.version explicitly in @babel/preset-env to avoid surprises.

Escalation: If after applying all checks the runtime errors or bundle size remain unchanged, create a minimal reproducible example and open an issue in the repository of your build tool (e.g., webpack, rollup), attaching the output of npx browserslist --debug and the bundle‑analyzer report.

Practical Verification Checklist

• Run npx browserslist --debug and confirm the output matches the intended support matrix.
• Inspect the generated bundle for core-js strings; count unique modules to spot duplication.
• Test in the oldest supported browser with the console open; no "missing polyfill" errors should appear.
• Verify TypeScript compilation with tsc --noEmit and ensure no global type errors.
• Check that the core-js version in package.json matches the corejs.version field in the Babel config.