From ffd9e64909d1ddc99212558364e397c5c9230ee6 Mon Sep 17 00:00:00 2001
From: Dan Bamikiya <dudeawesome732@gmail.com>
Date: Wed, 21 Apr 2021 19:24:15 +0100
Subject: [PATCH] Update usage.md (#2479)

* 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.
---
 docs/usage.md | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/docs/usage.md b/docs/usage.md
index e52966e22c..68cc016ca0 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -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:
@@ -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";
@@ -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