core-js ES module polyfills vs full bundle: Which import strategy yields optimal tree-shaking?

The Optimal Strategy for Tree-Shaking

To achieve optimal tree-shaking and minimum bundle size, individual ES module imports are the superior strategy. Importing the full core-js/stable or core-js/es bundle bypasses tree-shaking entirely, as it explicitly instructs the bundler to include the entire polyfill library regardless of whether your code utilizes the features.

Implementation and Behavior

When using a bundler (Webpack, Rollup, Vite) combined with Babel, the most efficient way to handle individual imports is through the useBuiltIns: 'usage' configuration. This approach automates the process by analyzing your source code and injecting only the specific imports required for your target environment.

• useBuiltIns: 'usage': The bundler includes only the polyfills actually invoked in your code. For example, if you only use Array.prototype.flat(), only that specific module is bundled.
• Full Bundle: Every single ES feature polyfill is included, significantly increasing the payload and risking prototype conflicts.

Prototype Patching and Conflict Mitigation

The method of import affects how the global environment is modified:

• Global Polyfills: Standard core-js imports modify native prototypes (e.g., Array.prototype). While convenient, this can cause conflicts if other libraries expect a different behavior or if a browser implements a slightly different version of a pending spec.
• Pure Polyfills (core-js-pure): To avoid prototype pollution entirely, use the core-js-pure package. This provides polyfills as standalone functions that do not modify the global object, making it the safest choice for library authors.

Verification Steps

To verify that your strategy is working as intended, perform the following checks:

1. Bundle Analysis: Run a production build and use a tool like webpack-bundle-analyzer. Search for core-js in the output; if you see a massive block containing almost every ES feature, tree-shaking is failing.
2. Runtime Validation: Test the application in your oldest supported browser. If a specific feature (like Promise.allSettled) fails despite being used in the code, your 'usage' configuration may be missing a target environment definition.

Diagnostic Detail Needed: To refine this recommendation, please specify your browserslist configuration. If you are targeting extremely legacy environments (e.g., IE11), the risk of missing a polyfill via 'usage' may outweigh the bundle size benefits of avoiding the full bundle.