Global Build vs. Ponyfill: Choosing core-js for Libraries

Answer

For a library that must not alter the consumer’s runtime, the core-js-pure ponyfill is the recommended build. It exports features as plain modules, guarantees no prototype mutation, and still allows granular imports for tree‑shaking.

Why core‑js‑pure is safer

• Prototype integrity: core-js patches built‑ins (e.g., Promise.prototype.then), which can clash with other polyfills or native implementations.
• Isolation: core-js-pure never touches global objects, so the consumer’s environment remains unchanged.
• Tree‑shaking friendliness: Each feature lives in its own file (e.g., core-js-pure/es/array/map), enabling bundlers to drop unused polyfills.
• Release consistency: The API surface of core-js-pure mirrors that of core-js, so upgrading to newer releases does not introduce new side‑effects.

Side‑effect overview when using the global build

• Loading core-js multiple times can overwrite earlier polyfill definitions, leading to unpredictable behavior.
• Prototype mutation may break type checks or runtime assumptions in downstream code that relies on native behaviour.

Tree‑shaking & granular imports

Both builds expose every feature as a separate module. Example imports:

// core‑js‑pure (ponyfill)
import { map } from 'core-js-pure/es/array/map';

// core‑js (global)
import 'core-js/es/array/map'; // mutates Array.prototype

When bundling with Rollup or Webpack, the pure import will appear as a direct dependency, while the global import will be treated as a side‑effectful script that may be included even if unused.

Consistency across releases

Both packages maintain the same feature set. Switching from core-js to core-js-pure (or vice versa) requires only a change in import paths; no API differences exist for the exported modules.

Integration test to confirm no global mutation

1. Store the native reference:

   const nativeMap = Array.prototype.map;
   

2. Import the ponyfill feature:

   import { map } from 'core-js-pure/es/array/map';
   

3. Assert identity:

   console.assert(Array.prototype.map === nativeMap, 'Prototype was mutated');
   

For the global build, the same test should reveal a change in the prototype, confirming the mutation.

When a global build might still be needed

If the library’s public API requires that consumers have a certain polyfilled built‑in (e.g., Array.flat must exist for internal logic), you must either document this requirement or provide a global polyfill yourself. In that case, keep the global build isolated and ensure it is the only source of prototype mutation.

Unresolved question answered

• Multiple global builds overwrite each other, causing inconsistent polyfills.
• core‑js‑pure guarantees no prototype mutation, preserving type compatibility.
• Integration test above confirms that a ponyfill import does not alter globals.

Next diagnostic step

Does your library need to expose any polyfilled built‑ins (e.g., Array.flat) to consumers? If yes, a global build or a consumer‑side polyfill may be required; otherwise, stick with core-js-pure.