babel/ babel-polyfills

JavaScript

Shell

Babel

Need help with babel-polyfills?

Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

babel

148 Stars

8 Forks

MIT License

212 Commits

13 Opened issues

Description

A set of Babel plugins that enable injecting different polyfills with different strategies in your compiled code.

Services available

Need anything else?

Contributors list

Readme

Babel Polyfills

Name: babel-polyfills
Brand: babel-polyfills
SKU: //babel/babel-polyfills
Rating: 2.12 (148 reviews)

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.

⚠️ These packages are highly experimental and they have not been tested in production applications yet. Also, we are still working on wiring some missing 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
.

Usage

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

tag:

html

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

{
  "plugins": [
    ["polyfill-es-shims", {
      "method": "usage-global",
      "targets": {
        "firefox": 65
      }
    }]
  ]
}




Promise.allSettled([
  p1,
  p2
]).finally(() =&gt; {
  console.log("Done!");
});

import "promise.prototype.finally/auto";
import "promise.allsettled/auto";

Promise.allSettled([
  p1,
  p2
]).finally(() =&gt; {
  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

Supported polyfills

| Polyfill | Plugin | Methods | | :------: | :----: | :-----: | |

[email protected]

babel-plugin-polyfill-corejs2

entry-global

usage-global

and

usage-pure

| |

[email protected]

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-js
and
es-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
.)

Injection methods

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:

you are not compiling your dependencies, but you want to be sure that they have all the necessary polyfills;
Babel's detection logic isn't smart enough to understand which functions you are using;

you want to have a single bundled file containing all the polyfills, without needing to regenerate it when your code changes.

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:

you need to keep your code size as small as possible, and only include what is effectively used;

your polyfill doesn't support a single entry point, but each of its features must be loaded separately.

Input code Output code

foo.flatMap(x =&gt; [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 =&gt; [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:

you are a library author, and don't want to "pollute" the global scope with the polyfills you are loading.

Input code Output code

foo.flatMap(x =&gt; [x, x+1]);
bar.trimLeft();
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 =&gt; [x, x + 1]);
_trimLeftInstanceProperty(bar).call(bar);
arr.includes(2);

History and Motivation

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:

By using
```
@babel/preset-env
```
's
```
useBuiltIns: "entry"
```
option, it is possible to inject polyfills for every ECMAScript functionality not natively supported by the target browsers;
By using
```
@babel/preset-env
```
's
```
useBuiltIns: "usage"
```
, Babel will only inject polyfills for unsupported ECMAScript features but only if they are actually used in the input souce code;
By using
```
@babel/plugin-transform-runtime
```
, Babel will inject ponyfills (which are "pure" and 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:

It wasn't possible to use
```
@babel/preset-env
```
's
```
targets
```
option with "pure" ponyfills, because
```
@babel/plugin-transform-runtime
```
is a completely separate package.
We forced our users to use
```
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.