Babel preset-env with usage-based core-js polyfills: architecture note

Problem and takeaway

Your bundle either ships syntax that older target runtimes cannot parse, or it ships polyfills for APIs your code never calls. The useful takeaway is to configure @babel/preset-env with explicit browserslist targets, core-js 3, useBuiltIns: "usage", and a deliberate modules setting, then verify the emitted output before shipping.

Requirements

• Babel 7 in the build pipeline.
• @babel/preset-env and core-js@3 installed as build dependencies.
• A defined set of target runtimes, expressed through browserslist.
• A distinction between application builds and library builds, because they need different module output.

core-js 2 is deprecated and lacks newer APIs; this design assumes core-js 3. Babel config files are build inputs, not runtime secrets, so they belong in version control alongside the source they transform.

Smallest suitable design

Use one project-wide babel.config.json at the repository root rather than per-directory .babelrc files. In a monorepo, root placement prevents different packages from receiving different transforms because of config lookup order.

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": "> 0.5%, last 2 versions, Firefox ESR, not dead",
        "corejs": 3,
        "useBuiltIns": "usage",
        "modules": false
      }
    ]
  ]
}

targets locks the browser list so a Babel or core-js release cannot silently change which syntax gets downleveled. useBuiltIns: "usage" tells Babel to insert import statements only for core-js APIs that appear statically in the source. modules: false preserves ES module syntax for library consumers while still transforming syntax such as optional chaining or nullish coalescing.

For an application consumed by a bundler, change modules to "auto" or omit it so Babel converts ES modules to CommonJS when the bundler expects that format. For a library, keep modules: false and let the downstream bundler handle module conversion.

Trust and data boundaries

The trust boundary is between source code and the emitted bundle. Babel reads source files and writes transformed files; it does not execute user-supplied data. browserslist targets come from package.json, .browserslistrc, or the Babel config itself, so treat those files as configuration inputs that require review before changes are merged.

Polyfill injection happens at transform time, not runtime. The final bundle size depends on whether the bundler tree-shakes the imported core-js entries, so Babel configuration alone does not determine the bytes shipped to users.

Operational checks

Run these checks in CI or locally before relying on the configuration.

1. Lock and inspect target runtimes

Run npx browserslist in the project root. It requires read access to the project’s browserslist configuration and writes only to standard output.

npx browserslist

Expected check: the output lists concrete browser versions. If the list changes after a dependency upgrade, review the change as you would any other build input. There is no write risk because this command is read-only.

2. Compile a sample file and inspect polyfill imports

Run Babel against a source file that uses an API such as Array.prototype.flat. Use a temporary output path so the command does not overwrite an existing build artifact.

npx babel src/example.js --out-file /tmp/example.compiled.js

Required permissions: read access to src/example.js and write access to /tmp. Risk: specifying an existing output path will overwrite it.

Expected check: open /tmp/example.compiled.js and look for import statements from core-js. If Babel statically detected flat, you should see a corresponding core-js import. If no core-js imports appear, Babel did not detect that API in that file, which means usage mode did not inject a polyfill for it.

3. Compare module output

Build once with "modules": false and once with "modules": "auto". Expected check: the first preserves export and import syntax; the second converts them to CommonJS require calls. Choose the setting that matches what your consumers or bundler expect.

4. Test in the oldest target runtime

Run the built output in the oldest browser or Node version listed in targets. Syntax transforms are verified in modern dev browsers, but missing runtime polyfills fail only in target runtimes.

Failure modes

• Dynamic code paths are missed. useBuiltIns: "usage" works on static imports and calls. If your code loads polyfills conditionally at runtime or uses eval-generated feature detection, Babel cannot see those dependencies and will not inject core-js imports.
• Bundle size can still grow. Usage mode adds import statements for detected APIs, but whether those imports are removed by tree-shaking depends on the bundler and on core-js’s side effects. Inspect the final bundle, not just the Babel output.
• Silent target drift. Omitting targets lets Babel use defaults that may shift between releases, changing the transform and polyfill set without any source change.
• Config inconsistency in monorepos. Placing babel.config.json somewhere other than the repository root, or mixing it with .babelrc files, can cause different packages to transform code differently.
• Dependency upgrades change output. Upgrading Babel or core-js may add, remove, or rewrite polyfill imports even when source code is unchanged.

Conditions that would change the design

• If you are building an application and your bundler already handles module conversion, keep modules: false to avoid double transpilation.
• If you need polyfills for APIs that Babel cannot statically detect, import core-js/stable directly at the application entry point instead of relying on usage mode.
• If you target only Node.js, express targets as a Node version range rather than a browserslist query, or use a Node-specific preset configuration.
• If bundle size is critical and your targets are modern, consider removing usage-based polyfills entirely and shipping feature detection instead.

Rollback

Changing babel.config.json alters build state. To roll back, restore the previous configuration file, rebuild the affected packages, and redeploy the previous bundle. No database migration is involved because this is a build-time change.

Limitations and verification status

This draft describes well-established Babel 7 behavior, but the commands and expected output have not been executed against your repository. Run the operational checks above before merging the configuration. If npx babel is unavailable, install @babel/cli as a dev dependency first.