Diagnosing core-js Array.prototype.flat polyfill inclusion in modern builds

Recognizable Condition

Your bundle analyzer flags an import of core-js/flat or inlined Array.prototype.flat polyfill code even though every target browser in your browserslist already supports the method natively. This inflates the final bundle size and masks tree‑shaking opportunities. Conversely, the polyfill may silently disappear in production when useBuiltIns: 'usage' is misconfigured, leaving Array.prototype.flat unavailable on environments that actually need it.

The condition typically stems from how core-js interacts with Babel’s preset‑env and the es-features option. Without explicit feature gating, core-js polyfills every method listed in its library, regardless of native support in the target runtime. This default behavior is intentional for maximum compatibility but becomes a size penalty when target environments already implement the method. If the polyfill is inlined, it can also increase the initial JavaScript parse time, affecting time‑to‑interactive on slow connections.

Cause & Diagnostic Table

Matching the observed bundle behavior to a root cause narrows the fix. The table below maps common conditions to their most likely origins.

Ordered Checks

1. Verify the core-js version. Run npm list core-js in the project root. This command requires npm access and will list the installed version. This article assumes core-js@3; core-js@2 does not provide a flat polyfill, and mixing the two versions causes duplicate injections and runtime errors.
2. Inspect the Babel preset‑env configuration. Open babel.config.js (or equivalent) and locate the useBuiltIns option. 'usage' polyfills based on individual method calls across the bundle, while 'entry' adds a single polyfill file at the top. Note which mode you are using, as the polyfill delivery strategy differs.
3. Check for the es-features array. Look for an es-features property in the preset options. If it is absent, core-js may include flat even when the target environment supports it natively. Adding es-features: ['flat'] restricts polyfill injection to only environments lacking the method.
4. Confirm target environment coverage. Review package.json browserslist or @babel/preset-env targets. Polyfill behavior is tied to these targets; adjusting them can change which methods are polyfilled. For example, adding > 0.25%, not dead broadens the target set and may affect polyfill necessity.
5. Inspect transpiled output. Run a production build and search the output for flat or core-js/flat. Verify that the code appears only when the target lacks native support. If you see flat polyfill code in a bundle for a modern Chrome environment, the configuration is not restricting injection as intended.

Fixes Tied to Findings

• Restrict polyfill injection with es-features. Add es-features: ['flat'] to your Babel preset options. This tells core-js to include the flat polyfill only in environments that do not natively implement it, reducing unnecessary bundle weight without sacrificing compatibility.
• Migrate from core-js@2 to core-js@3. If your project still references core-js@2, upgrade. core-js@2 does not support flat, and running both versions simultaneously causes duplicate polyfill injections and runtime conflicts. Update package.json to pin a single version and re‑run the build.
• Align useBuiltIns with your bundle strategy. For per‑method, tree‑shakable polyfills, keep useBuiltIns: 'usage' and ensure your loader (e.g., Babel loader, Webpack plugin) respects the es-features option. If you prefer a single polyfill entry point, switch to useBuiltIns: 'entry' but expect more code to ship, as this mode polyfills all listed methods regardless of individual usage.
• Remove duplicate core-js references. Audit package.json and any manual import 'core-js/...' statements. Keep a single version and a single preset configuration across all build pipelines. If other team members maintain separate configs, coordinate a unified approach.

Escalation Criteria

If adjusting es-features and version pins does not resolve bundle bloat or runtime behavior, verify that your build pipeline respects sideEffects flags and that no other plugin is overriding Babel’s polyfill logic. Persistent duplicate polyfill injections across builds, or errors such as Cannot read properties of undefined (polyfill) in mixed‑environment tests, indicate the need to involve your build‑tool maintainer or upgrade to the latest core-js@3 and @babel/preset-env versions that include refined feature detection.

Additionally, if your project uses multiple bundlers (e.g., Webpack and Rollup) each with their own Babel configuration, ensure that the es-features and useBuiltIns settings are consistent across all pipelines. Mismatched configurations can silently re‑introduce polyfill code in one bundle while another omits it, leading to inconsistent runtime behavior, especially in CI pipelines that test against multiple node versions.