From 37ac459cfd0eafdf5bbb3d083aa82f0f2a3c9b75 Mon Sep 17 00:00:00 2001
From: Ambrose Chua <ambrose@hey.com>
Date: Fri, 5 Nov 2021 20:33:22 +0800
Subject: [PATCH] docs: Improve clarity of "Loading and configuring" (#1323)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: Improve clarity of "Loading and configuring"

* Update README.md

Co-authored-by: Linus Unnebäck <linus@folkdatorn.se>

Co-authored-by: Linus Unnebäck <linus@folkdatorn.se>
---
 README.md | 37 +++++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index f5e01624d..1a7466276 100644
--- a/README.md
+++ b/README.md
@@ -111,21 +111,21 @@ npm install node-fetch
 
 ## Loading and configuring the module
 
+### ES Modules (ESM)
+
 ```js
 import fetch from 'node-fetch';
 ```
 
-If you want to patch the global object in node:
+### CommonJS
 
-```js
-import fetch from 'node-fetch';
+`node-fetch` from v3 is an ESM-only module - you are not able to import it with `require()`. 
 
-if (!globalThis.fetch) {
-	globalThis.fetch = fetch;
-}
-```
+If you cannot switch to ESM, please use v2 which remains compatible with CommonJS. Critical bug fixes will continue to be published for v2.
 
-`node-fetch` is an ESM-only module - you are not able to import it with `require`. We recommend you stay on v2 which is built with CommonJS unless you use ESM yourself. We will continue to publish critical bug fixes for it.
+```sh
+npm install node-fetch@2
+```
 
 Alternatively, you can use the async `import()` function from CommonJS to load `node-fetch` asynchronously:
 
@@ -134,6 +134,27 @@ Alternatively, you can use the async `import()` function from CommonJS to load `
 const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));
 ```
 
+### Providing global access
+
+To use `fetch()` without importing it, you can patch the `global` object in node:
+
+```js
+// fetch-polyfill.js
+import fetch from 'node-fetch';
+
+if (!globalThis.fetch) {
+    globalThis.fetch = fetch;
+    globalThis.Headers = Headers;
+    globalThis.Request = Request;
+    globalThis.Response = Response;
+}
+
+// index.js
+import './fetch-polyfill'
+
+// ...
+```
+
 ## Upgrading
 
 Using an old version of node-fetch? Check out the following files: