preset-env useBuiltIns and corejs: pinning the installed core-js major for compiled files

Polyfill Placement: Library vs. Application

The choice between @babel/preset-env and @babel/plugin-transform-runtime depends on who controls the global environment.

For Applications

Applications should use @babel/preset-env with useBuiltIns: 'usage' or 'entry'. Because the application is the final entry point, it is responsible for patching the global environment (e.g., window.Promise) to ensure all dependencies—including those in node_modules—can execute. core-js should be listed as a production dependency.

For Libraries

Libraries should use @babel/plugin-transform-runtime with the corejs: 3 option. This replaces global references with aliased imports (e.g., _corejs_pure_promise), preventing the library from polluting the global scope of the application that consumes it. In this setup, @babel/runtime-corejs3 is added as a dependency.

Pinning the core-js Version

To prevent resolution failures or the injection of outdated polyfills, the corejs option in your Babel configuration must match the major (and ideally minor) version installed in your package.json.

Configuration Example:

// babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "useBuiltIns": "usage",
        "corejs": "3.38", // Pin to the installed minor version
        "targets": "defaults"
      }
    ]
  ]
}

If you specify "corejs": 3, Babel defaults to 3.0, which may miss newer polyfills available in your installed version. Specifying the minor version (e.g., "3.38") ensures Babel utilizes the full feature set of the installed package.

Verification with debug: true

Setting debug: true within @babel/preset-env provides a detailed console output during compilation. It confirms:

• Targets: The specific browser versions Babel is targeting based on your browserslist.
• Polyfills: The exact core-js modules being injected into each file.

If the debug output shows polyfills being injected that are missing from your node_modules, or if the bundle fails to resolve a module, there is a mismatch between your corejs config string and the installed version.

Practical Verification Steps

1. Check package.json for the installed core-js version.
2. Match that version string in babel.config.json.
3. Run the build with debug: true and verify the "Polyfills" section of the log.

Note: To provide a more specific recommendation on useBuiltIns: 'usage', please specify if you are using a bundler (like Webpack or Vite) that excludes node_modules from the Babel loader.