This guide walks through the three main ways to use core-js: polyfilling everything at once, polyfilling only the features you need, and using core-js without global namespace pollution.
Install core-js
Add core-js to your project. Pin to the full minor version to ensure all relevant polyfills are included. Import at the top of your entry point
Add the core-js import as the very first statement in your application’s entry file — before any other imports or application code.import 'core-js/actual';
// rest of your application...
Load core-js at the very top of your application entry point. Importing it after other modules that use native built-ins can cause conflicts — for example, third-party code may cache a reference to a partially-specified Symbol.iterator before core-js has had a chance to correct it.
Write modern JavaScript
With core-js loaded, you can use stable ES features and Stage 3 proposals freely, regardless of your target environments.Promise.try(() => 42).then(it => console.log(it)); // => 42
Array.from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]
[1, 2].flatMap(it => [it, it]); // => [1, 1, 2, 2]
structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
Usage patterns
Pattern 1: Polyfill everything at once
Import a single namespace entry point to polyfill a broad set of features in one line.
import 'core-js/actual';
Promise.try(() => 42).then(it => console.log(it)); // => 42
Array.from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]
[1, 2].flatMap(it => [it, it]); // => [1, 1, 2, 2]
structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
The /actual/ namespace is the recommended import for most projects. It includes all stable ECMAScript features, Web platform standards, and Stage 3 proposals — the features closest to becoming part of the standard — without pulling in experimental early-stage proposals that are still subject to significant change.
| Import | Includes |
|---|
core-js/full | Everything, including early-stage proposals |
core-js/actual | Stable ES + Web standards + Stage 3 proposals |
core-js/stable | Stable ES + Web standards only |
core-js/es | Stable ECMAScript only |
Pattern 2: Polyfill specific features
Import individual feature modules to keep your bundle as small as possible. Each import targets exactly one constructor, method, or proposal.
import 'core-js/actual/promise';
import 'core-js/actual/set';
import 'core-js/actual/iterator';
import 'core-js/actual/array/from';
import 'core-js/actual/array/flat-map';
import 'core-js/actual/structured-clone';
Promise.try(() => 42).then(it => console.log(it)); // => 42
Array.from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]
[1, 2].flatMap(it => [it, it]); // => [1, 1, 2, 2]
structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
import 'core-js/actual/promise'; // all Promise features
import 'core-js/actual/array/find-last'; // just Array.prototype.findLast
import 'core-js/stable/queue-microtask'; // stable Web API
import 'core-js/es/array/from'; // ES-only Array.from
Pattern 3: Use core-js-pure (no global pollution)
If you are building a library or a component that must not modify the host environment’s globals, install core-js-pure and import implementations directly.
Prototype methods are exported as standalone functions. Constructors are exported as classes.
import Promise from 'core-js-pure/actual/promise';
import Set from 'core-js-pure/actual/set';
import from from 'core-js-pure/actual/array/from';
import flatMap from 'core-js-pure/actual/array/flat-map';
import structuredClone from 'core-js-pure/actual/structured-clone';
Promise.try(() => 42).then(it => console.log(it)); // => 42
from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]
flatMap([1, 2], it => [it, it]); // => [1, 1, 2, 2]
structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
With core-js-pure, prototype methods like Array.prototype.flatMap cannot be called as methods on array instances. They are re-exported as static functions that accept the array as their first argument.
Using with Babel
If you are using @babel/preset-env, set useBuiltIns to 'usage' or 'entry' and specify the exact minor version of core-js you have installed. Babel will automatically inject only the imports required for your configured target environments.
{
"presets": [
[
"@babel/preset-env",
{
"useBuiltIns": "usage",
"corejs": "3.49"
}
]
]
}
useBuiltIns: 'usage', do not add core-js imports yourself — Babel inserts them automatically per file based on what you use.
With useBuiltIns: 'entry', place a single import 'core-js/actual' at the top of your entry point, and Babel will replace it with the precise set of module imports your targets need.
Using with swc
swc supports the same entry and usage modes. Configure via .swcrc:
{
"env": {
"targets": "> 0.25%, not dead",
"mode": "entry",
"coreJs": "3.49"
}
}
Next steps