Babel plugin for automatic injection of core-js polyfills. It analyzes your code and adds only the polyfills that are actually needed for your target environments. Works with both global (core-js) and pure (@core-js/pure) variants. Documentation.

Methods

The plugin supports three injection methods: entry-global, usage-global, and usage-pure.

[!IMPORTANT] You should specify the used minor core-js version, like version: '4.1', instead of version: '4'.

entry-global

Replaces imports of core-js to import only required for a target environment modules. So, for example,

import 'core-js/actual';

with chrome 135 target will be replaced to:

import 'core-js/modules/es.suppressed-error.constructor';
import 'core-js/modules/es.async-disposable-stack.constructor';
import 'core-js/modules/es.disposable-stack.constructor';
import 'core-js/modules/es.iterator.concat';
import 'core-js/modules/es.regexp.escape';
// ...only the modules not yet supported by Chrome 135

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

{
  "plugins": [["@core-js", {
    "method": "entry-global",
    "version": "4.0",
    "targets": { "chrome": 135 }
  }]]
}

usage-global

Automatically adds to the top of each file import of polyfills for features used in this file and not supported by target environments — no manual imports required. So, for example,

const p = Promise.allSettled([f1, f2]);
'test'.at(-1);

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

import 'core-js/modules/es.promise.all-settled';
import 'core-js/modules/es.string.at';

const p = Promise.allSettled([f1, f2]);
'test'.at(-1);

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

{
  "plugins": [["@core-js", {
    "method": "usage-global",
    "version": "4.0",
    "targets": { "ie": 11 }
  }]]
}

usage-pure

Like usage-global, but without global namespace pollution. It automatically replaces usage of modern features from the JS standard library to imports from @core-js/pure, so instead of:

import from from '@core-js/pure/actual/array/from';
import at from '@core-js/pure/actual/instance/at';

from(items);
at([1, 2, 3]).call([1, 2, 3], -1);

you can write just:

Array.from(items);
[1, 2, 3].at(-1);

{
  "plugins": [["@core-js", {
    "method": "usage-pure",
    "version": "4.0",
    "targets": { "ie": 11 }
  }]]
}

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | method | string | required | 'entry-global', 'usage-global', or 'usage-pure' | | version | string | '4.0' | Used core-js version, it's recommended to specify the used minor version like '4.1'. Special values: 'node_modules', 'package.json' | | targets | string | object | from browserslist config / all engines | Browserslist query or an object of minimum environment versions, same as @core-js/compat | | mode | string | 'actual' | Entry point layer: 'es', 'stable', 'actual', or 'full' (makes no sense for entry-global) | | package | string | 'core-js' / '@core-js/pure' | Package name for import paths (defaults depend on method) | | additionalPackages | string[] | [] | Additional package names to recognize as core-js (for entry-global) | | include | (string \| RegExp)[] | [] | Force include specific polyfills by module name, entry path (for pure version), or pattern | | exclude | (string \| RegExp)[] | [] | Force exclude specific polyfills by module name, entry path (for pure version), or pattern | | shouldInjectPolyfill | function | undefined | Custom function to decide whether to inject a polyfill | | shippedProposals | boolean | false | Treat proposals that have been shipped in browsers as stable features | | configPath | string | '.' | Directory to search for a browserslist config file | | ignoreBrowserslistConfig | boolean | false | Ignore browserslist config files, use only explicit targets | | absoluteImports | boolean | string | false | Use absolute paths for injected imports | | debug | boolean | false | Print injected polyfills to console |

version

The core-js version installed in your project. The plugin uses this to determine which polyfill modules and entry points are available.

It's recommended to specify the minor version (e.g., '4.1') rather than just the major version ('4.0'), so that the plugin can use polyfills added in minor releases.

Special values:

• 'node_modules' — reads the version from the installed core-js package (core-js/package.json)
• 'package.json' — reads the version range from the project's package.json dependencies, devDependencies, or peerDependencies

{
  "plugins": [["@core-js", {
    "method": "usage-global",
    "version": "4.1",
    "targets": { "ie": 11 }
  }]]
}

package

The package name used in generated import paths. Defaults to 'core-js' for entry-global and usage-global, and '@core-js/pure' for usage-pure.

Override this if you use a custom package name:

{
  "plugins": [["@core-js", {
    "method": "usage-global",
    "version": "4.0",
    "package": "my-core-js-version"
  }]]
}

additionalPackages

Additional package names to recognize as core-js entry points in entry-global mode. By default, only core-js is recognized. If you re-export core-js from another package, add it here so the plugin can process those imports too.

{
  "plugins": [["@core-js", {
    "method": "entry-global",
    "version": "4.0",
    "package": "my-core-js-version",
    "additionalPackages": ["core-js"]
  }]]
}

mode

Controls which features are available:

• 'es' — stable ECMAScript only
• 'stable' — stable ECMAScript + web standards
• 'actual' — stable + Stage 3 proposals (default)
• 'full' — all features including early-stage proposals

{
  "plugins": [["@core-js", {
    "method": "usage-global",
    "version": "4.0",
    "mode": "stable",
    "targets": { "firefox": 100, "safari": "15.4" }
  }]]
}

targets

When targets is not specified, the plugin reads targets from your browserslist config (.browserslistrc, browserslist field in package.json, or BROWSERSLIST env variable). You can control where to look for the config with configPath, or disable config discovery with ignoreBrowserslistConfig.

{
  "plugins": [["@core-js", {
    "method": "usage-global",
    "version": "4.0",
    "targets": { "chrome": 100, "firefox": 115, "safari": "16.4" }
  }]]
}

include / exclude

Force include or exclude specific polyfills regardless of target environment. Accepts module names (like es.array.from), entry point paths (for pure version, like array/from), or regular expressions. Entry point paths are automatically expanded to the corresponding module names. Cannot be used together with shouldInjectPolyfill.

{
  "plugins": [["@core-js", {
    "method": "usage-global",
    "version": "4.0",
    "targets": { "chrome": 135 },
    "include": ["es.array.at"],
    "exclude": ["es.string.at"]
  }]]
}

{
  "plugins": [["@core-js", {
    "method": "usage-pure",
    "version": "4.0",
    "targets": { "chrome": 135 },
    "include": ["array/at"],
    "exclude": ["string/at"]
  }]]
}

shouldInjectPolyfill

A callback that gives full control over which polyfills are injected. It receives the polyfill module name and a boolean indicating whether it would be injected by default (based on targets), and returns a boolean. Cannot be used together with include / exclude.

// babel.config.js
module.exports = {
  plugins: [['@core-js', {
    method: 'usage-global',
    version: '4.0',
    shouldInjectPolyfill(name, shouldInject) {
      // exclude object polyfills, keep everything else as-is
      if (name.startsWith('es.object.')) return false;
      return shouldInject;
    },
  }]],
};

shippedProposals

When true and mode is 'es' or 'stable', upgrades the effective mode to 'actual', allowing Stage 3+ proposals.

configPath

Directory path to search for a browserslist config file. Useful in monorepos where the config is not in the project root.

{
  "plugins": [["@core-js", {
    "method": "usage-global",
    "version": "4.0",
    "configPath": "./packages/my-app"
  }]]
}

ignoreBrowserslistConfig

When true, the plugin will not read any browserslist config files. Only the explicitly provided targets will be used. If no targets are provided either, the target is assumed to be all engines — all polyfills will be injected.

absoluteImports

When true, injected core-js imports will use absolute filesystem paths instead of package names. When a string, it will be used as the base path. This can be useful in monorepos to ensure that all files resolve to the same core-js installation.

debug

When true, the plugin will log to the console all polyfills that are injected into each file.

Disable comments

You can use comments to disable polyfill injection for specific lines or entire files, similar to ESLint disable comments:

// core-js-disable-file

Disables polyfill injection for the entire file. Can appear anywhere in the file.

arr.includes(x); // core-js-disable-line

Disables polyfill injection for the current line.

// core-js-disable-next-line
arr.includes(x);

Disables polyfill injection for the next line.

Both // and /* */ comment styles are supported. You can add a reason after --:

// core-js-disable-next-line -- custom includes implementation
arr.includes(x);