A set of Babel plugins that enable injecting different polyfills with different strategies in your compiled code. Additionally, this repository contains a package that helps with creating providers for other polyfills.
This repository implements what was initially proposed at babel/babel#10008.
If you are looking for some quick setup examples, or just want to see how to migrate your config, please check
docs/migration.md.
The main Babel packages only transform JavaScript syntax: you also need to load a polyfill, to make native functions (Array.prototype.flat) or built-in objects (Reflect) work in older browsers.
The easiest way to do so is to directly load the polyfill using a "><script src="https://unpkg.com/[email protected]/minified.js">script>
However, this simple approach can potentially include a lot of unnecessary code. The Babel plugins implemented in this repository automatically inject the polyfills in your code, while trying to only load what is really needed. It does this based on your compilation targets and on what you are using in your code.
These plugins (we are calling them "polyfill providers") support different injection methods, to better fit your needs.
For example, if you want to inject imports to es-shims polyfills by adding the missing functions to the global objects, you could configure Babel as such:
| Configuration | Input code | Output code |
|---|---|---|
{
"targets": { "firefox": 65 },
"plugins": [
["polyfill-es-shims", {
"method": "usage-global"
}]
]
}
|
Promise.allSettled([
p1,
p2
]).finally(() => {
console.log("Done!");
}); |
{
console.log("Done!");
});">
import "promise.prototype.finally/auto"; import "promise.allsettled/auto"; Promise.allSettled([ p1, p2 ]).finally(() => { console.log("Done!"); }); |
If you want to see more configuration examples, you can check the migration docs: docs/migration.md.
If you are interested in reading about all the options supported by these plugins, you can check the usage docs: docs/usage.md.
| Polyfill | Plugin | Methods |
|---|---|---|
core-js@2 |
babel-plugin-polyfill-corejs2 |
entry-global, usage-global and usage-pure |
core-js@3 |
babel-plugin-polyfill-corejs3 |
entry-global, usage-global and usage-pure |
es-shims |
babel-plugin-polyfill-es-shims |
usage-global and usage-pure |
regenerator-runtime |
babel-plugin-polyfill-regenerator |
entry-global, usage-global and usage-pure |
We are maintaining support for
core-jsandes-shims, but we encourage you to implement a provider for your own polyfill, or for your favorite one! One of our goals is to encourage competition between different polyfills, to better balance the different trade offs like spec compliancy and code size.If you want to implement support for a custom polyfill, you can use
@babel/helper-define-polyfill-provider. (docs/polyfill-provider.md.)
Polyfill plugins can expose three different injection methods: entry-global, usage-global and usage-pure.
Note that polyfill plugins don't automatically add the necessary package(s) to your dependencies, so you must explicitly list them in your package.json.
All the examples assume that you are targeting Chrome 62.
The entry-global method replaces a single simple import to the whole polyfill with imports to the specific features not supported by the target environments. It is most useful when you want to be sure that every unsupported function is available, regardless of what you are using in the code you are compiling with Babel. You might want to use this method if:
| Input code | Output code |
|---|---|
import "core-js"; |
import "core-js/modules/es7.array.flat-map.js";
import "core-js/modules/es6.array.sort.js";
import "core-js/modules/es7.promise.finally.js";
import "core-js/modules/es7.symbol.async-iterator.js";
import "core-js/modules/es7.string.trim-left.js";
import "core-js/modules/es7.string.trim-right.js";
import "core-js/modules/web.timers.js";
import "core-js/modules/web.immediate.js";
import "core-js/modules/web.dom.iterable.js"; |
The usage-global method injects imports to polyfills attached to the global scope, but only for unsupported features which are used in your code. You might want to use this method if:
| Input code | Output code |
|---|---|
foo.flatMap(x => [x, x+1]);
bar.trimLeft();
arr.includes(2); |
[x, x + 1]);
bar.trimLeft();
arr.includes(2);">
import "core-js/modules/es.array.flat-map.js"; import "core-js/modules/es.array.unscopables.flat-map.js"; import "core-js/modules/es.string.trim-start.js"; foo.flatMap(x => [x, x + 1]); bar.trimLeft(); arr.includes(2); |
The usage-pure method injects imports to polyfills for unsupported features which are used in your code, without attaching the polyfills to the global scope but importing them as normal functions. You might want to use this method if:
| Input code | Output code |
|---|---|
foo.flatMap(x => [x, x+1]);
bar.trimLeft();
arr.includes(2); |
[x, x + 1]);
_trimLeftInstanceProperty(bar).call(bar);
arr.includes(2);">
import _flatMapInstanceProperty from "core-js-pure/stable/instance/flat-map.js"; import _trimLeftInstanceProperty from "core-js-pure/stable/instance/trim-left.js"; _flatMapInstanceProperty(foo).call(foo, x => [x, x + 1]); _trimLeftInstanceProperty(bar).call(bar); arr.includes(2); |
In the last three years and a half, @babel/preset-env has shown its full potential in reducing bundle sizes not only by not transpiling supported syntax features, but also by not including unnecessary core-js polyfills.
So far Babel provided three different ways to inject core-js polyfills in the source code:
@babel/preset-env's useBuiltIns: "entry" option, it is possible to inject self-installing polyfills for every ECMAScript functionality not natively supported by the target browsers;@babel/preset-env's useBuiltIns: "usage", Babel will only inject self-installing polyfills for unsupported ECMAScript features but only if they are actually used in the input souce code;@babel/plugin-transform-runtime, Babel will inject "pure" polyfills (which, unlike self-installing ones, don't pollute the global scope) for every used ECMAScript feature supported by core-js. This is usually used by library authors.Our old approach has two main problems:
@babel/preset-env's targets option with "pure" polyfills, because @babel/plugin-transform-runtime is a completely separate package.core-js if they wanted a Babel integration. core-js is a good and comprehensive polyfill, but it doesn't fit the needs of all of our users.With this new packages we are proposing a solution for both of these problem, while still maintaining full backward compatibility.
See our CONTRIBUTING.md to get started with setting up the repo.
