Skip to content

Commit

Permalink
Update usage.md (#2479)
Browse files Browse the repository at this point in the history
* Update usage.md

Updated usage.md to not recommend the use of `[@babel/polyfill](https://babeljs.io/docs/en/babel-polyfill)`, which is deprecated. Solves #2171

* Update usage.md to include usage of core-js polyfill

Update the documentation to state first how to poliyfill with core-js. Solves #2240, #2163, #2332 and #2006

* fix typo in previous commit

Fix in usage.md where I was referring(linking) to where deprecated was stated

* update usage.md to describe regenerator-runtime polyfills

I updated this doc to describe the use of regenerator-runtime polyfills and when to use them.
  • Loading branch information
danBamikiya authored Apr 21, 2021
1 parent 1e2d775 commit ffd9e64
Showing 1 changed file with 29 additions and 3 deletions.
32 changes: 29 additions & 3 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ The entire process to set this up involves:

```sh
npm install --save-dev @babel/core @babel/cli @babel/preset-env
npm install --save @babel/polyfill
```

2. Creating a config file named `babel.config.json` (requires `v7.8.0` and above) in the root of your project with this content:
Expand Down Expand Up @@ -174,7 +173,7 @@ Now the `env` preset will only load transformation plugins for features that are
## Polyfill
> 🚨 As of Babel 7.4.0, this package has been deprecated in favor of directly including `core-js/stable` (to polyfill ECMAScript features) and `regenerator-runtime/runtime` (needed to use transpiled generator functions):
> 🚨 <span id="polyfill-deprecated">As</span> of Babel 7.4.0, this package has been deprecated in favor of directly including `core-js/stable` (to polyfill ECMAScript features) and `regenerator-runtime/runtime` (needed to use transpiled generator functions):
>
> ```js
> import "core-js/stable";
Expand Down Expand Up @@ -232,7 +231,34 @@ require("core-js/modules/es.promise.finally");
Promise.resolve().finally();
```
If we weren't using the `env` preset with the `"useBuiltIns"` option set to `"usage"` we would've had to require the full polyfill _only once_ in our entry point before any other code.
If we weren't using the `env` preset with the `"useBuiltIns"` option set to `"usage"` (defaults to "false") we would've had to require the full polyfill _only once_ in our entry point before any other code.
For example:
```json
{
"presets": [
[
"@babel/env",
{
"targets": {
"edge": "17",
"firefox": "60",
"chrome": "67",
"safari": "11.1"
},
"useBuiltIns": "entry"
}
]
]
}
```
Then import [core-js](https://github.com/zloirock/core-js) (to polyfill ECMAScript features) and [regenerator runtime](https://github.com/facebook/regenerator/blob/master/packages/regenerator-runtime/runtime.js) (needed only if you are transpiling generators) first, in our entry file to emulate a full ES2015+ environment since [@babel/polyfill](polyfill.md) has been <a href="#polyfill-deprecated">deprecated</a>:
```js
import "core-js/stable";
import "regenerator-runtime/runtime";
```
## Summary
Expand Down

0 comments on commit ffd9e64

Please sign in to comment.