Configure Babel preset-env with useBuiltIns: usage for selective polyfilling

Desired outcome

Transpile modern JavaScript with Babel while injecting only the polyfills that are actually needed for the declared target environments, keeping the final bundle as small as possible.

Prerequisites

• Node.js version 14 or newer.
• npm or yarn available in the project.
• A source directory (e.g., src/) containing ES2015+ code.
• No existing Babel configuration that conflicts with @babel/preset-env.

Procedure

1. Install the required packages:

   # Run in the project root
   npm install --save-dev @babel/core @babel/preset-env core-js@3
   # or with yarn
   yarn add -D @babel/core @babel/preset-env core-js@3
   

2. Create a Babel configuration file named .babelrc (or babel.config.json) in the project root with the following content:

   {
     "presets": [
       [
         "@babel/preset-env",
         {
           "targets": ">0.25%, not dead",
           "useBuiltIns": "usage",
           "corejs": 3
         }
       ]
     ]
   }
   

   Explanation:

   • targets defines the browsers or environments you support; the example covers browsers with >0.25% global usage that are not officially dead.
   • useBuiltIns: "usage" tells Babel to analyze each file and import only the polyfills required by the features actually used in that file.
   • corejs: 3 matches the version of the core-js package installed.
3. Add a build script to package.json (if not already present):

   "scripts": {
     "build": "babel src --out-dir lib --copy-files"
   }
   

4. Run the build:

   npm run build
   # or
   yarn run build
   

   This will transpile files from src/ to lib/, inserting selective core-js imports where needed.

   Expected checks

   1. Inspect a generated file in lib/ (e.g., lib/example.js). You should see:
      • Transpiled syntax (e.g., arrow functions turned into function expressions).
      • Import statements like import "core-js/modules/es.array.map"; only for features actually used in the source file.
      • No imports for polyfills that correspond to features already supported by your targets (e.g., Promise if targeting modern browsers).
   2. Optional: compare bundle sizes before and after enabling useBuiltIns: "usage" using a tool like webpack --profile or rollup with the same targets. Expect a reduction in the size contributed by core-js.
   3. Run the built code in a target browser (e.g., Chrome 80) or via a test suite that exercises the transpiled features. The console should show no warnings about missing polyfills.

   Recovery options

   If you encounter runtime errors indicating a missing polyfill:

   • Verify that the targets list truly includes the environment where the error occurs. Adjust the query (e.g., add IE 11) and rebuild.
   • If your code uses dynamic import() or eval that Babel cannot statically analyze, switch to the entry mode:

     {
       "presets": [
         ["@babel/preset-env", {
           "targets": ">0.25%, not dead",
           "useBuiltIns": "entry",
           "corejs": 3
         }]
       ]
     }
     

     Then add a single import at your application entry point:

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

     This guarantees all polyfills for the targets are included, at the cost of a larger bundle.

   • Ensure the version of core-js installed matches the corejs number in the preset; mismatches can cause runtime errors. Reinstall with npm install core-js@3 if needed.