core-js 3 feature-path migration: side-by-side version serving during zero-downtime rollout

Answer the question first

Core‑JS 2 and Core‑JS 3 cannot be loaded in the same runtime without risking prototype replacement conflicts. The library explicitly does not support side‑by‑side operation. Therefore, you must switch all entry points at once or serve separate bundles per major version.

Why the conflict happens

• Both major versions patch global prototypes (e.g., Array.prototype.includes, Promise, Object.defineProperty).
• When the second version loads, it overwrites the first version’s patches, sometimes with different semantics or missing features.
• Code that was written against the first polyfill may break or behave inconsistently after the overwrite.

Confirmed facts

1. The Core‑JS documentation states that loading two major versions simultaneously is unsupported.
2. In a test page, importing core-js/fn/promise (v2) followed by core-js/features/promise (v3) shows that the second import replaces the first and changes the Promise prototype.
3. Using @babel/preset‑env with useBuiltIns: 'usage' or 'entry' injects the polyfills at bundle build time, so the runtime receives only the chosen major version.

Safe staged‑rollout strategy

1. Build two independent bundles. One bundle contains only Core‑JS 2 imports (e.g., core-js/fn/* or core-js/stable). The other bundle contains only Core‑JS 3 imports (core-js/features/* or core-js/stable).
2. Serve the bundles via distinct URLs or CDN paths. For example:

   https://cdn.example.com/app-v2.js
   https://cdn.example.com/app-v3.js

3. Use a feature flag, A/B test, or user‑agent detection to decide which bundle a particular request receives. Ensure that a single page never pulls both scripts.
4. Deploy the Core‑JS 3 bundle to a small percentage of traffic (canary). Run integration tests and monitor for prototype‑related errors.
5. Once confidence is reached, switch the flag to route all traffic to the Core‑JS 3 bundle and retire the old bundle.

Choosing entry points during the transition

• Prefer core-js/features/* over the aggregate stable if you need to avoid large global side effects. Each features module patches only the specific feature it exports.
• Even features modules still mutate prototypes, so they must never coexist with fn modules from Core‑JS 2 in the same runtime.
• If you must use core-js/stable, do so only in the new bundle and never mix it with any Core‑JS 2 imports.

Verification checklist

• Run a full regression suite after the switch.
• Inspect global prototypes in the browser console for unexpected overrides.
• Use static analysis (e.g., ESLint import/no-unresolved) to ensure no module imports both core-js/fn/* and core-js/features/* in the same bundle.

Missing diagnostic detail

Do you use dynamic imports or code‑splitting that might load different polyfill versions in separate chunks? That could expose a runtime to both major versions inadvertently.