Resolving Polyfill Bloat and Missing Features in core-js

The Problem: Bundle Bloat vs. Runtime Crashes

When targeting multiple browser environments, developers often face a binary failure: either the application crashes in older browsers because a modern JavaScript method (like Array.prototype.flat) is missing, or the production bundle size swells by hundreds of kilobytes because every possible polyfill is included regardless of actual usage.

The core issue usually lies in a mismatch between how core-js is imported and how the transpiler (typically Babel) is configured to handle those imports. This results in either "over-polyfilling" (importing the entire stable library) or "under-polyfilling" (missing critical features in specific environments).

Diagnostic Matrix: Identifying the Polyfill Failure

Use this table to determine which configuration error is affecting your build.

Symptom	Likely Cause	Diagnostic Signal
TypeError: ... is not a function in old browsers	Under-polyfilling	Bundle analysis shows core-js is missing or useBuiltIns: false.
Excessive JS bundle size (>100KB increase)	Over-polyfilling	import "core-js/stable" is present without Babel transformation.
Polyfills working in dev, failing in prod	Environment Mismatch	browserslist config is ignored or differs between build stages.

Step-by-Step Resolution Path

Step 1: Verify the Browserslist Configuration

Before adjusting core-js, you must define your target environment. Babel and core-js rely on a .browserslistrc file or a browserslist key in package.json to decide which polyfills are necessary.

# Example .browserslistrc
> 0.5%
last 2 versions
Firefox ESR
not dead

Step 2: Align Babel's useBuiltIns Strategy

Depending on your bundle size requirements, choose one of the following two configurations in your babel.config.json or .babelrc. Note: Ensure corejs version matches your installed core-js package (e.g., 3.30).

Option A: The "Entry" Method (Balanced Control)

Use this if you want a single point of control for all polyfills based on your target browsers.

• Babel Config: Set "useBuiltIns": "entry".
• Required Action: Add import "core-js/stable"; at the very top of your main entry file.
• Result: Babel replaces that single import with a list of specific imports required only for the browsers defined in your browserslist.

Option B: The "Usage" Method (Maximum Optimization)

Use this to minimize bundle size by only including polyfills for features actually written in your code.

• Babel Config: Set "useBuiltIns": "usage".
• Required Action: Remove all global core-js imports from your entry file.
• Result: Babel analyzes each file and injects import "core-js/modules/es.array.flat.js" only where .flat() is detected.

Step 3: Handling Global Pollution (The Library Case)

If you are developing a library, using the methods above is dangerous because they modify the global prototypes (e.g., Array.prototype), which can break the consumer's application. In this case, avoid useBuiltIns and use @babel/plugin-transform-runtime with the corejs option.

// babel.config.json
{
  "plugins": [["@babel/plugin-transform-runtime", {
    "corejs": 3
  }]]
}

This replaces global references with non-polluting aliases from core-js-pure.

Verification and Validation

To ensure the fix is active and not introducing bloat, perform these checks:

1. Bundle Inspection: Run a build and search the output JS file for "core-js/modules/". If you see hundreds of entries while targeting only modern browsers, your browserslist is too broad.
2. Runtime Check: Open the application in the oldest supported browser. Open the developer console and manually call the problematic method (e.g., [].flat()). If it returns a value instead of a TypeError, the polyfill is active.
3. Size Comparison: Compare the bundle size of useBuiltIns: "entry" vs "usage" using a tool like webpack-bundle-analyzer.

Rollback Procedure

If the new configuration causes build failures or runtime errors:

1. Revert babel.config.json to "useBuiltIns": false.
2. Add import "core-js/stable"; to the entry point to return to a "safe" (though bloated) state where all stable features are available.