Duplicate core-js major versions in dependency tree cause conflicting built-in polyfills

Question

The goal is to select a core-js import strategy for a reusable library that polyfills ECMAScript features without mutating global built-ins or conflicting with other dependencies.
Importing bare core-js mutates Array.prototype, Promise, and other globals, which can mask missing native support and collide with other polyfills. core-js-pure avoids global mutation but changes import patterns and may affect bundle tree-shaking. Subpath imports such as core-js/stable and core-js/proposals separate finished ECMAScript features from stage-specific proposals.
Assume core-js v3 is installed; v2 is end-of-life and v4 has no firm release date. Duplicate major versions may coexist in a dependency tree.
Which import entry point should a library use to avoid global mutation while preserving tree-shaking? Should proposals be imported separately from stable features? What mechanism can an application use to detect and resolve duplicate core-js v2 and v3 installations?

Tasadduq Burney · Answer

A reusable library should import from core-js/pure using explicit feature subpaths, keep proposals in a separate core-js/proposals import, and let the application root detect duplicate versions with npm ls core-js or yarn why core-js and resolve them with a resolutions field.
Import entry point
Use core-js/pure with explicit feature paths, for example import { flat } from 'core-js/pure/array/flat'. This avoids mutating Array.prototype, Promise, and other globals, and it allows bundlers to tree-shake features the library does not use. Do not use the bare core-js entry or core-js/stable in library code, because both patch globals by default.
Stable features versus proposals
Import finished ECMAScript features from core-js/pure. Import proposals separately from core-js/proposals only when the library requires a specific stage-3 or stage-4 API. Keeping them separate prevents unfinished APIs from entering the default bundle and reduces risk if a proposal changes between core-js releases.
Duplicate core-js versions
Run npm ls core-js or yarn why core-js from the application root to surface conflicting v2 and v3 installations. If duplicates exist and you control the application, enforce one version with an npm resolutions field or yarn resolutions, pinning core-js to a single v3 release.
Steps for this case

Replace bare core-js or core-js/stable imports with explicit core-js/pure feature subpaths.
Add core-js/proposals imports only for specific proposal features, and pin the core-js minor version so proposal behavior does not drift.
Run npm ls core-js or yarn why core-js to confirm one resolved version.
If duplicates remain in an application you own, add "resolutions": { "core-js": "3.x.x" } to package.json and reinstall.

Missing diagnostic detail
Is this library published to external consumers, or is it used only inside one application? A library should not force a resolutions entry on consumers; if it is published, document core-js as a peer dependency and rely on core-js/pure instead.
Verification
Inspect the built bundle to confirm only the imported core-js/pure subpaths appear. Confirm that importing pure did not assign polyfills to globals by checking the bundle output for global built-in assignments.

Duplicate core-js major versions in dependency tree cause conflicting built-in polyfills

1 answer

Import entry point

Stable features versus proposals

Duplicate core-js versions

Steps for this case

Missing diagnostic detail

Verification

Your perspective belongs here.

0 question comments