Guide · Open source

How to use core-js: polyfills, imports and setup

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

core-js is an MIT-licensed JavaScript library that adds newer standard features, such as Promises, Symbols, collections, iterators and typed arrays, to environments that do not support them yet. It also includes some web standard features such as URL. This guide shows how to install it, import only the parts you need and use it without changing global objects, so you can decide whether it fits your project.

core-jszloirock/core-js · ★ 25.5k · MIT Install options & downloads

Quick start

1Install the package. Run npm install core-js@3 in your project.
2Pick an import style. Use import 'core-js/actual' for broad coverage, or import individual modules such as core-js/actual/promise for smaller output.
3Import at the entry point. Add the import near the top of your application entry file so features are available before your code runs.
4Switch to core-js-pure for libraries. If you are publishing a library, import from core-js-pure so you do not change global objects for the people using it.
5Check your build setup. If you use Babel or swc, review the matching section of the README and the documentation at core-js.io.

What does core-js do?

core-js provides polyfills: pieces of code that add newer standard features to environments that lack them. The library covers ECMAScript features up to the most recent edition it supports, plus some cross-platform WHATWG and W3C features such as URL.

You can load only the features you need, or use it in a way that does not add anything to the global namespace.

Install core-js from npm

core-js is distributed as an npm package. The README gives this command to install the current major version 3 line.

Requires Node.js or a JavaScript bundler setup, since the library is installed through npm.
The main documentation lives at core-js.io; the README points there.

npm install core-js@3

Load all features or only the ones you need

The simplest option is to import the actual entry point, which loads a broad set of features. For smaller bundles, import individual modules by path, such as core-js/actual/promise or core-js/actual/array/from.

Importing only specific features gives you fine-grained control over what ends up in your code.

Import everything: import 'core-js/actual';
Import single features: import 'core-js/actual/promise';, import 'core-js/actual/set';, import 'core-js/actual/array/flat-map';

import 'core-js/actual';

Promise.try(() => 42).then(it => console.log(it)); // -> 42

Use core-js-pure to avoid global pollution

If you are writing a library and do not want to change global objects, use the core-js-pure variant. You import each built-in explicitly and use it as a local binding instead of relying on the global one.

This is the approach the README describes for library authors who want newer built-ins without modifying globals.

import Promise from 'core-js-pure/actual/promise';
import Set from 'core-js-pure/actual/set';
import flatMap from 'core-js-pure/actual/array/flat-map';

flatMap([1, 2], it => [it, it]); // => [1, 1, 2, 2]

Use core-js with Babel or swc

The README has sections on Babel and swc, which cover how polyfills are handled through a build setup. Babel-related entries it names include @babel/polyfill, @babel/preset-env, @babel/runtime and babel-plugin-polyfill-corejs3. Check those sections on core-js.io for configuration details, since the README points to the documentation site for them.

Teams already using Babel or swc can let their build tooling handle standard library polyfills rather than importing them by hand.

Babel: @babel/polyfill, @babel/preset-env, @babel/runtime, babel-plugin-polyfill-corejs3
swc: covered in its own README section

What people use it for

Making Promise.try, Set union and Iterator helpers work in older engines that lack them.
Using Array.prototype.flatMap or structuredClone in a codebase that must run on older browsers.
Writing a library that uses newer built-ins without modifying the global environment, via core-js-pure.
Keeping bundle size small by importing only the specific features an app uses.

Frequently asked questions

How do I install core-js?

Run npm install core-js@3 in your project. The README uses this command for installation through npm.

Is core-js free to use?

core-js is released under the MIT licence, as stated in the project information. Check the LICENSE file in the repository for the full terms.

What do I need to use core-js?

The README mentions Node.js or a JavaScript bundler setup, since core-js is installed as an npm package.

What is the difference between core-js and core-js-pure?

core-js changes global objects so built-ins are available everywhere. core-js-pure imports each feature explicitly, so it does not add anything to the global namespace, which suits library authors.

What are the alternatives to core-js?

The project lists Babel polyfill, es-shims and polyfill.io as comparable projects. Choose based on whether you use a build tool and how much control you need over imports.

Do I need core-js if I only target modern browsers?

Probably not. The project notes that projects targeting only modern evergreen browsers do not need polyfills, and the extra code adds weight without benefit.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

core-js suits web developers who must support older engines, teams using Babel or swc, and library authors who want to avoid touching globals. If your project only targets modern evergreen browsers, you can skip it, and if you want an end-user application, this is a code library with no interface.

Install options & downloads