Choosing a core-js Polyfill Strategy for Babel Builds

The Polyfill Dilemma: Bundle Size vs. Runtime Safety

When targeting multiple browser versions, you face a trade-off: including every possible polyfill ensures the application won't crash on legacy engines but bloats the bundle for modern users. Conversely, omitting polyfills reduces load times but risks TypeError: undefined is not a function errors in production.

The solution is integrating core-js via @babel/preset-env. This allows you to automate polyfill injection based on your browserslist configuration, ensuring you only ship the code your target audience actually needs.

Decision Matrix: useBuiltIns Modes

The useBuiltIns option in @babel/preset-env determines how Babel handles the core-js library. Choosing the wrong mode can lead to either missing features or redundant code.

Mode	Mechanism	Bundle Size	Reliability	Best For
false (Default)	No automatic injection.	Smallest	Low	Evergreen-only targets.
'usage'	Injects imports per-file based on AST analysis.	Small	Medium	Most applications.
'entry'	Rewrites a single global import into a target-specific list.	Medium/Large	High	Critical apps with dynamic code.

Trade-offs and Engineering Constraints

The 'usage' Blind Spot

While useBuiltIns: 'usage' is the most efficient, it relies on static analysis. Babel scans your code for patterns like Array.prototype.flat() and adds the corresponding import. However, it cannot detect features used indirectly, such as those required by a third-party dependency in node_modules or features triggered by internal engine protocols (e.g., Symbol.species).

Application vs. Library Strategy

The strategy changes based on what you are shipping:

• Applications: Use global polyfills. You control the environment, so mutating Array.prototype is acceptable to ensure consistency.
• Libraries: Avoid global polyfills. If your library adds a polyfill to the global scope, it may conflict with the consuming application's version. Use @babel/runtime-corejs3, which aliases polyfills to non-global helpers (e.g., using a local version of Promise instead of overriding window.Promise).

Implementation: Configuring core-js@3

Ensure you are using core-js@3. Version 2 is legacy and lacks support for many modern ES2015+ features and proposal-stage specifications.

Step 1: Install dependencies
Run this in your project root with administrator/sudo permissions if required by your environment:

npm install core-js@3

Step 2: Configure Babel
In your babel.config.json or .babelrc, define the corejs version and the injection mode:

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": "defaults",
        "useBuiltIns": "usage",
        "corejs": 3
      }
    ]
  ]
}

Step 3: Entry Point (Required for 'entry' mode only)
If you chose useBuiltIns: 'entry', you must add the following to the very top of your main entry file (e.g., index.js):

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

Verification and Validation

To verify that polyfills are being injected correctly, you can inspect the compiled output without running the full application.

1. Bundle Inspection: Run your build command and search the output bundle for core-js/modules. If you see imports like core-js/modules/es.array.flat.js, the injection is working.
2. Target Check: Run npx browserslist in your terminal to see exactly which browsers your config is targeting. Cross-reference this with the core-js-compat tool to see which polyfills are required for those specific versions.
3. Runtime Smoke Test: In your oldest supported browser, open the console and check for a feature you know is missing natively (e.g., console.log(Array.prototype.flat)). If it returns a function rather than undefined, the polyfill is active.

Rollback and Cleanup

If you encounter bundle bloat or conflicts, revert the useBuiltIns setting to false and remove core-js from your dependencies. If you are migrating from @babel/polyfill (which is deprecated), remove that package entirely and replace it with the core-js and regenerator-runtime imports described above.