docs: Add example for loading ESM from CommonJS

README.md

@@ -124,6 +124,15 @@ if (!globalThis.fetch) {
 }
 ```
 
+`node-fetch` is an ESM-only module - you are not able to import it with `require`. If you are unable to use ESM in your project you can use the async `import()` function from CommonJS to load `node-fetch` asynchronously:
+
+```js
+// mod.cjs
+const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));
+```
+
+Alternatively, you can stay on v2 which is built with CommonJS.
+
 ## Upgrading
 
 Using an old version of node-fetch? Check out the following files:

docs/CHANGELOG.md

@@ -1,11 +1,16 @@
-Changelog
-=========
+# Changelog
+All notable changes will be recorded here.
 
-# 3.x release
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] yyyy-mm-dd
+
+- docs: Add example for loading ESM from CommonJS (#1236)
 
 ## v3.0.0-beta.10
 
-- **Breaking:** minimum supported Node.js version is now 12.8.
+- **Breaking:** minimum supported Node.js version is now 12.20.
 - **Breaking:** node-fetch is now a pure ESM module.
 - Other: update readme to inform users about ESM.
 - Other: update dependencies.
@@ -374,3 +379,5 @@ See [changelog on 1.x branch](https://github.com/node-fetch/node-fetch/blob/1.x/
 ## v0.1
 
 - Major: initial public release
+
+[Unreleased]: https://github.com/node-fetch/node-fetch/compare/v3.0.0-beta.10...HEAD

docs/v3-UPGRADE-GUIDE.md

@@ -19,17 +19,27 @@ other comparatively minor modifications.
 
 # Breaking Changes
 
-## Minimum supported Node.js version is now 10.16
+## Minimum supported Node.js version is now 12.20
 
-Since Node.js will deprecate version 8 at the end of 2019, we decided that node-fetch v3.x will not only drop support for Node.js 4 and 6 (which were supported in v2.x), but also for Node.js 8. We strongly encourage you to upgrade, if you still haven't done so. Check out Node.js' official [LTS plan] for more information on Node.js' support lifetime.
+Since Node.js 10 has been deprecated since May 2020, we have decided that node-fetch v3 will drop support for Node.js 4, 6, 8, and 10 (which were previously supported). We strongly encourage you to upgrade if you still haven't done so. Check out the Node.js official [LTS plan] for more information.
+
+## Converted to ES Module
+
+This module was converted to be a ESM only package in version `3.0.0-beta.10`.
+Using require to load an ES module is not supported because ES modules have asynchronous execution. Instead, use import() to load an ES module from a CommonJS module.
+
+```js
+// mod.cjs
+const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));
+```
 
 ## The `timeout` option was removed.
 
-Since this was never part of the fetch specification, it was removed. AbortSignal offers a more finegrained control of request timeouts, and is standardized in the Fetch spec. For convenience, you can use [timeout-signal](https://github.com/Richienb/timeout-signal) as a workaround:
+Since this was never part of the fetch specification, it was removed. AbortSignal offers more fine grained control of request timeouts, and is standardized in the Fetch spec. For convenience, you can use [timeout-signal](https://github.com/node-fetch/timeout-signal) as a workaround:
 
 ```js
-const timeoutSignal = require('timeout-signal');
-const fetch = require('node-fetch');
+import timeoutSignal from 'timeout-signal';
+import fetch from 'node-fetch';
 
 const {AbortError} = fetch
 
@@ -57,11 +67,12 @@ Prior to v3.x, we included a `browser` field in the package.json file. Since nod
 If you want charset encoding detection, please use the [fetch-charset-detection] package ([documentation][fetch-charset-detection-docs]).
 
 ```js
-const fetch = require('node-fetch');
-const convertBody = require('fetch-charset-detection');
+import fetch from 'node-fetch';
+import convertBody from 'fetch-charset-detection';
 
-fetch('https://somewebsite.com').then(res => {
-	const text = convertBody(res.buffer(), res.headers);
+fetch('https://somewebsite.com').then(async res => {
+    const buf = await res.arrayBuffer();
+    const text = convertBody(buf, res.headers);
 });
 ```
 
@@ -70,7 +81,7 @@ fetch('https://somewebsite.com').then(res => {
 When attempting to parse invalid json via `res.json()`, a `SyntaxError` will now be thrown instead of a `FetchError` to align better with the spec.
 
 ```js
-const fetch = require('node-fetch');
+import fetch from 'node-fetch';
 
 fetch('https://somewebsitereturninginvalidjson.com').then(res => res.json())
 // Throws 'Uncaught SyntaxError: Unexpected end of JSON input' or similar.