core-js/stable vs core-js/actual for shared library polyfills

Question

Polyfill Delivery in Shared Libraries
When developing a shared library intended for diverse environments, there is a tension between providing necessary polyfills and avoiding side effects in the host application. Core-js provides two primary documented paths for this: core-js/stable, which patches global objects, and core-js/actual, which provides polyfills as module bindings without mutating the global namespace.

Global Mutation Trade-offs
Using core-js/stable ensures that all scripts on the page, including third-party dependencies, have access to the patched built-ins. However, this mutates globalThis, which may violate the constraints of a side-effect-free library. Conversely, core-js/actual keeps the library isolated and tree-shakeable, but it provides no coverage for other scripts in the bundle graph that may assume these globals exist.

Since core-js resolves to native implementations when they are correct, mixing these namespaces does not create duplicate identities on modern engines. However, on legacy engines, the boundary between global and explicit polyfills remains a manual architectural decision with no tooling to enforce consistency across a dependency graph.

Should a shared library prioritize global stability by using core-js/actual and delegating global patching to the host application?
How can a library ensure its own internal dependencies are polyfilled without risking global namespace pollution in the consumer's environment?

Muntasir · Answer

Answer to the Question
1️⃣ Yes – a side‑effect‑free library should use core-js/actual and let the host decide whether to patch globals. 2️⃣ To satisfy its own internal dependencies, the library should import only the polyfills it needs from core-js/actual and keep those imports explicit.
Why core-js/actual is the safer default

It exposes polyfills as named module bindings, leaving globalThis untouched.
Tree‑shaking can remove unused polyfills, keeping bundle size minimal.
Other scripts on the page remain unaffected unless the host explicitly imports core-js/stable or patches globals itself.

Ensuring internal polyfills without global pollution

List every ES feature your library relies on (e.g., Array.flat, Promise.allSettled).
Import those features directly from core-js/actual:
import 'core-js/actual/array/flat';
import 'core-js/actual/promise/all-settled';

Configure your bundler to preserve side‑effect‑free modules:

Webpack – set sideEffects: false in package.json or use sideEffects: ['**/*.js'] for polyfill modules.
Rollup – use the @rollup/plugin-node-resolve with preferBuiltins: false and external: [] for polyfills.
Vite – no special config needed; Vite treats core-js/actual imports as side‑effect‑free.

Run a host test page that imports only your library. Verify that Array.prototype.flat is available in your library’s scope but globalThis.flat remains undefined unless the host imports core-js/stable.

For legacy browsers that lack native support, ship a small bootstrap module that the host can opt‑in to:
export function installGlobals() {
  import('core-js/stable');
}
This keeps the decision in the consumer’s hands.

When to consider core-js/stable inside the library

If the library is intended to run in environments where the consumer cannot or will not patch globals.
If you need to guarantee that third‑party scripts on the same page see the polyfilled features.

In those rare cases, document the side effect clearly and provide a --no-global build flag that skips the global patching.
Missing Diagnostic
Do you need the library to support browsers older than ES2019 (e.g., IE11, Edge 14)? That would influence whether you keep the global patching strategy or provide a dedicated legacy bundle.

core-js/stable vs core-js/actual for shared library polyfills

Polyfill Delivery in Shared Libraries

Global Mutation Trade-offs

1 answer

Answer to the Question

Why `core-js/actual` is the safer default

Ensuring internal polyfills without global pollution

When to consider `core-js/stable` inside the library

Missing Diagnostic

Your perspective belongs here.

0 question comments