useBuiltIns: 'entry' vs 'usage' — covering third-party dependencies without shipping dead polyfills

Choosing the Right Polyfill Strategy

For a project with a mixed dependency graph containing both ES2015+ and legacy packages, useBuiltIns: 'entry' produces fewer production incidents. While it increases bundle size by including all polyfills required by your browserslist targets, it provides a global safety net. This ensures that any third-party dependency—regardless of whether it was transpiled by your pipeline—has access to the standard library features it expects.

The Trade-off: 'entry' vs 'usage'

The fundamental difference lies in how Babel identifies what to include:

• 'entry': Rewrites a single global import (e.g., import "core-js/stable";) into a list of specific imports based on your target environment. It assumes that if a feature is missing in the browser, something in your dependency tree might need it.
• 'usage': Scans your source code and injects imports only for features it statically detects. Because Babel typically excludes node_modules from transformation, it cannot see which polyfills your dependencies require, leading to runtime ReferenceError or TypeError in older browsers.

Implementing 'usage' for Specific Dependencies

If you prioritize bundle size and want to use 'usage', you must manually bridge the gap for untranspiled dependencies. You can do this by using the include option to force-inject specific polyfills that you know your dependencies require, without re-transpiling the entire node_modules folder.

Example configuration for @babel/preset-env:

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "useBuiltIns": "usage",
        "corejs": 3,
        "include": [
          "es.array.flat",
          "es.object.entries"
        ]
      }
    ]
  ]
}

Verification and Safety

To ensure your configuration is stable, perform these three checks:

1. Version Alignment: Run npm ls core-js. Ensure the installed major version matches the corejs value in your Babel config (e.g., corejs: 3) to avoid duplicate polyfills or missing features.
2. Bundle Analysis: Use a tool like webpack-bundle-analyzer. If using 'entry', you will see a larger block of core-js modules; if using 'usage', this block should be significantly smaller.
3. Runtime Validation: Test the application in the oldest browser defined in your browserslist. Any missing polyfill in 'usage' mode will typically manifest as a crash during the execution of a third-party library.

Diagnostic Requirement: To refine this recommendation, identify which specific third-party packages in your graph rely on non-standard or newer ES features. If the list is short, 'usage' with a tailored include array is viable; if the list is long or unknown, 'entry' is the safer choice.