GitHub - zloirock/core-js: Standard Library

logo

Welcome to our new website, core-js.io, where our documentation is moving!

I highly recommend reading this: So, what's next?

Modular standard library for JavaScript. Includes polyfills for ECMAScript up to 2026: promises, symbols, collections, iterators, typed arrays, many other features, ECMAScript proposals, some cross-platform WHATWG / W3C features and proposals like URL. You can load only required features or use it without global namespace pollution.

core-js@3, babel and a look into the future

Raising funds

core-js isn't backed by a company, so the future of this project depends on you. Become a sponsor or a backer if you are interested in core-js: Open Collective, Patreon, Boosty, Bitcoin ( bc1qlea7544qtsmj2rayg0lthvza9fau63ux0fstcz ), Alipay.

Example of usage:

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]

Iterator.concat([1, 2], function * (i) { while (true) yield i++; }(3))
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => Set { 1, 2, 3 }

You can load only required features:

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]

Iterator.concat([1, 2], function * (i) { while (true) yield i++; }(3))
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => Set { 1, 2, 3 }

Or use it without global namespace pollution:

import Promise from 'core-js-pure/actual/promise';
import Set from 'core-js-pure/actual/set';
import Iterator from 'core-js-pure/actual/iterator';
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]

Iterator.concat([1, 2], function * (i) { while (true) yield i++; }(3))
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => Set { 1, 2, 3 }

Index

Usage⬆

Installation:⬆

# global version
npm install --save [email protected]
# version without global namespace pollution
npm install --save [email protected]
# bundled global version
npm install --save [email protected]

`postinstall` message⬆

The core-js project needs your help, so the package shows a message about it after installation. If it causes problems for you, you can disable it:

ADBLOCK=true npm install
# or
DISABLE_OPENCOLLECTIVE=true npm install
# or
npm install --loglevel silent

CommonJS API⬆

You can import only the polyfills you need, like in the examples at the top of README.md. CommonJS entry points are available for all polyfilled methods / constructors and namespaces. Just some examples:

// polyfill all `core-js` features, including early-stage proposals:
import 'core-js';
// or:
import 'core-js/full';
// polyfill all actual features - stable ES, web standards and stage 3 ES proposals:
import 'core-js/actual';
// polyfill only stable features - ES and web standards:
import 'core-js/stable';
// polyfill only stable ES features:
import 'core-js/es';

// if you want to polyfill `Set`:
// all `Set`-related features, with early-stage ES proposals:
import 'core-js/full/set';
// stable required for `Set` ES features, features from web standards and stage 3 ES proposals:
import 'core-js/actual/set';
// stable required for `Set` ES features and features from web standards
// (DOM collections iterator in this case):
import 'core-js/stable/set';
// only stable ES features required for `Set`:
import 'core-js/es/set';
// the same without global namespace pollution:
import Set from "core-js-pure/full/set";
import Set from "core-js-pure/actual/set";
import Set from "core-js-pure/stable/set";
import Set from "core-js-pure/es/set";

// if you want to polyfill just the required methods:
import 'core-js/full/set/intersection';
import 'core-js/actual/array/find-last';
import 'core-js/stable/queue-microtask';
import 'core-js/es/array/from';

// polyfill async iterator helpers proposal:
import 'core-js/proposals/async-iterator-helpers';
// polyfill all stage 2+ proposals:
import 'core-js/stage/2';

[!TIP] The usage of the /actual/ namespace is recommended since it includes all actual JavaScript features and does not include unstable early-stage proposals that are available mainly for experiments.

[!WARNING]

The modules path is an internal API, does not inject all required dependencies and can be changed in minor or patch releases. Use it only for a custom build and/or if you know what you are doing.

If you use core-js with the extension of native objects, recommended to load all core-js modules at the top of the entry point of your application, otherwise, you can have conflicts.

For example, Google Maps uses its own Symbol.iterator, conflicting with Array.from, URLSearchParams and / or something else from core-js, see related issues.

Such conflicts are also resolvable by discovering and manually adding each conflicting entry from core-js.

core-js is extremely modular and uses a lot of very tiny modules, because of that, for usage in browsers, bundle up core-js instead of using a loader for each file; otherwise, you will have hundreds of requests.

CommonJS and prototype methods without global namespace pollution⬆

In the pure version, we can't pollute prototypes of native constructors. Because of that, prototype methods are transformed into static methods, like in the examples above. But with transpilers, we can use one more trick - bind operator and virtual methods. For this case, there are /virtual/ entry points. Example:

import fill from 'core-js-pure/actual/array/virtual/fill';
import findIndex from 'core-js-pure/actual/array/virtual/find-index';

Array(10)::fill(0).map((a, b) => b * b)::findIndex(it => it && !(it % 8)); // => 4

[!WARNING] The bind operator is an early-stage ECMAScript proposal and usage of this syntax can be dangerous.

Babel⬆

core-js is integrated with babel and is the base for polyfilling-related babel features:

[!NOTE] useBuiltIns and corejs options described below are available only in Babel 7; in Babel 8, they were replaced with babel-plugin-polyfill-corejs3.

`@babel/polyfill`⬆

@babel/polyfill IS just the import of stable core-js features and regenerator-runtime for generators and async functions, so loading @babel/polyfill means loading the global version of core-js without ES proposals.

Now it's deprecated in favor of separate inclusion of required parts of core-js and regenerator-runtime and, for backward compatibility, @babel/polyfill is still based on core-js@2.

As a full equivalent of @babel/polyfill, you can use the following:

import 'core-js/stable';
import 'regenerator-runtime/runtime';

`@babel/preset-env`⬆

@babel/preset-env has useBuiltIns option, which optimizes the use of the global version of core-js. With useBuiltIns option, you should also set corejs option to the used version of core-js, like corejs: '3.51'.

[!IMPORTANT] It is recommended to specify the used minor core-js version, like corejs: '3.51', instead of corejs: 3, since with corejs: 3, modules added in minor core-js releases will not be injected.

useBuiltIns: 'entry' replaces imports of core-js with imports of only the modules required for a target environment. So, for example,

import 'core-js/stable';

with chrome 71 target will be replaced just to:

import 'core-js/modules/es.array.unscopables.flat';
import 'core-js/modules/es.array.unscopables.flat-map';
import 'core-js/modules/es.object.from-entries';
import 'core-js/modules/web.immediate';
// ...and the rest of the modules not yet supported by Chrome 71

It works for all entry points of global version of core-js and their combinations, for example for

import 'core-js/es';
import 'core-js/proposals/set-methods';
import 'core-js/full/set/map';

with chrome 71 target you will have as the result:

import 'core-js/modules/es.array.unscopables.flat';
import 'core-js/modules/es.array.unscopables.flat-map';
import 'core-js/modules/es.object.from-entries';
import 'core-js/modules/esnext.set.difference';
import 'core-js/modules/esnext.set.intersection';
import 'core-js/modules/esnext.set.is-disjoint-from';
import 'core-js/modules/esnext.set.is-subset-of';
import 'core-js/modules/esnext.set.is-superset-of';
import 'core-js/modules/esnext.set.map';
import 'core-js/modules/esnext.set.symmetric-difference';
import 'core-js/modules/esnext.set.union';
// ...and the rest of the modules not yet supported by Chrome 71

useBuiltIns: 'usage' adds to the top of each file imports of polyfills for features used in this file and not supported by target environments, so for:

// first file:
let set = new Set([1, 2, 3]);

// second file:
let array = Array.of(1, 2, 3);

if the target contains an old environment like IE 11 we will have something like:

// first file:
import 'core-js/modules/es.array.iterator';
import 'core-js/modules/es.object.to-string';
import 'core-js/modules/es.set';

var set = new Set([1, 2, 3]);

// second file:
import 'core-js/modules/es.array.of';

var array = Array.of(1, 2, 3);

By default, @babel/preset-env with useBuiltIns: 'usage' option only polyfills stable features, but you can enable polyfilling of proposals by the proposals option, as corejs: { version: '3.51', proposals: true }.

[!IMPORTANT] In the case of useBuiltIns: 'usage', you should not add core-js imports by yourself, they will be added automatically.

`@babel/runtime`⬆

@babel/plugin-transform-runtime with corejs: 3 option simplifies work with the core-js-pure. It automatically replaces the usage of modern features from the JS standard library to imports from the version of core-js without global namespace pollution, so instead of:

import from from 'core-js-pure/stable/array/from';
import flat from 'core-js-pure/stable/array/flat';
import Set from 'core-js-pure/stable/set';
import Promise from 'core-js-pure/stable/promise';

from(new Set([1, 2, 3, 2, 1]));
flat([1, [2, 3], [4, [5]]], 2);
Promise.resolve(32).then(x => console.log(x));

you can write just:

Array.from(new Set([1, 2, 3, 2, 1]));
[1, [2, 3], [4, [5]]].flat(2);
Promise.resolve(32).then(x => console.log(x));

By default, @babel/plugin-transform-runtime only polyfills stable features, but like in @babel/preset-env, you can enable polyfilling of proposals by proposals option, as corejs: { version: 3, proposals: true }.

[!WARNING] If you use @babel/preset-env and @babel/plugin-transform-runtime together, use corejs option only in one place since it's duplicate functionality and will cause conflicts.

`babel-plugin-polyfill-corejs3`⬆

babel-plugin-polyfill-corejs3 is a babel plugin for injection of core-js polyfills. In Babel 8, useBuiltIns and corejs options were removed from @babel/preset-env and @babel/plugin-transform-runtime in favor of this plugin; it also works with Babel 7. It has 3 methods: entry-global (like useBuiltIns: 'entry'), usage-global (like useBuiltIns: 'usage') and usage-pure (like @babel/plugin-transform-runtime with corejs: 3 option). Like with corejs option, it's recommended to specify the used minor core-js version by version option, and polyfilling of proposals can be enabled by proposals: true option. Example of configuration in babel.config.json:

{
  "plugins": [["polyfill-corejs3", { "method": "usage-global", "version": "3.51" }]]
}

swc⬆

Fast JavaScript transpiler swc contains integration with core-js, that optimizes work with the global version of core-js. Like @babel/preset-env, it has 2 modes: usage and entry, but usage mode still works not so well as in babel. Example of configuration in .swcrc:

{
  "env": {
    "targets": "> 0.25%, not dead",
    "mode": "entry",
    "coreJs": "3.51"
  }
}

Configurable level of aggressiveness⬆

By default, core-js sets polyfills only when they are required. That means that core-js checks if a feature is available and works correctly or not and if it has no problems, core-js uses native implementation.

But sometimes core-js feature detection could be too strict for your case. For example, Promise constructor requires support for unhandled rejection tracking and @@species.

Sometimes we could have an inverse problem - a knowingly broken environment with problems not covered by core-js feature detection.

For those cases, we could redefine this behavior for certain polyfills:

const configurator = require('core-js/configurator');

configurator({
  useNative: ['Promise'],                                 // polyfills will be used only if natives are completely unavailable
  usePolyfill: ['Array.from', 'String.prototype.padEnd'], // polyfills will be used anyway
  useFeatureDetection: ['Map', 'Set'],                    // default behavior
});

require('core-js/actual');

It does not work with some features. Also, if you change the default behavior, even core-js internals may not work correctly.

Custom build⬆

In some cases, it could be useful to exclude some core-js features or to generate a polyfill for target engines. You can use the core-js-builder package for that.

Supported engines and compatibility data⬆

core-js tries to support all possible JS engines and environments with ES3 support. Some features have a higher lower bar - for example, some accessors can properly work only from ES5, promises require a way to set a microtask or a task, etc.

However, I have no possibility to test core-js absolutely everywhere - for example, testing in IE7- and some other ancient engines was stopped. You can see the list of definitely supported engines in the compatibility table at the link below. Write if you have issues or questions with the support of any engine.

The core-js project provides (as the core-js-compat package) all required data about the necessity of core-js modules, entry points, and tools to work with it - it's useful for integration with tools like babel or swc. If you want to help, you could take a look at the related section of CONTRIBUTING.md. The visualization of compatibility data and the browser tests runner is available here, the example:

compat-table

Measured star growth

README.md

Welcome to our new website, core-js.io, where our documentation is moving!

I highly recommend reading this: So, what's next?

Raising funds

Index

Usage⬆

Installation:⬆

postinstall message⬆

CommonJS API⬆

CommonJS and prototype methods without global namespace pollution⬆

Babel⬆

@babel/polyfill⬆

@babel/preset-env⬆

@babel/runtime⬆

babel-plugin-polyfill-corejs3⬆

swc⬆

Configurable level of aggressiveness⬆

Custom build⬆

Supported engines and compatibility data⬆

Features:⬆

ECMAScript⬆

ECMAScript: Object⬆

ECMAScript: Function⬆

ECMAScript: Error⬆

ECMAScript: Array⬆

ECMAScript: Iterator⬆

ECMAScript: String and RegExp⬆

ECMAScript: Number⬆

ECMAScript: Math⬆

ECMAScript: Date⬆

ECMAScript: Promise⬆

Unhandled rejection tracking⬆

ECMAScript: Symbol⬆

Caveats when using Symbol polyfill:⬆

ECMAScript: Collections⬆

Map⬆

Set⬆

WeakMap⬆

WeakSet⬆

ECMAScript: Explicit resource management⬆

ECMAScript: Typed arrays⬆

ECMAScript: Reflect⬆

ECMAScript: JSON⬆

ECMAScript: globalThis⬆

ECMAScript proposals⬆

Finished proposals⬆

Stage 3 proposals⬆

Stage 2.7 proposals⬆

Stage 2 proposals⬆

Caveats:⬆

Stage 1 proposals⬆

Stage 0 proposals⬆

Pre-stage 0 proposals⬆

Web standards⬆

self⬆

structuredClone⬆

Base64 utility methods⬆

setTimeout and setInterval⬆

setImmediate⬆

queueMicrotask⬆

URL and URLSearchParams⬆

DOMException⬆

Iterable DOM collections⬆

Iteration helpers⬆

Missing polyfills⬆

Explore related projects

codecrafters-io/build-your-own-x

public-apis/public-apis

morluto/rea

openclaw/openclaw

`postinstall` message⬆

`@babel/polyfill`⬆

`@babel/preset-env`⬆

`@babel/runtime`⬆

`babel-plugin-polyfill-corejs3`⬆

Caveats when using `Symbol` polyfill:⬆

`self`⬆

`structuredClone`⬆

`setTimeout` and `setInterval`⬆

`setImmediate`⬆

`queueMicrotask`⬆

`URL` and `URLSearchParams`⬆

`DOMException`⬆