docs: Add example for loading ESM from CommonJS

README.md

@@ -124,6 +124,13 @@ 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()` from CommonJS to load `node-fetch` asynchronously:
+
+```js
+// mod.cjs
+const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));
+```
+
 ## 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 to this project will be documented in this file.
 
-# 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
+
+- Other: Updated README & v3-upgrade docs (#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.
 
+## 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(mod => mod.default(...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 a more fine grained 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:
 
 ```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.