diff --git a/README.md b/README.md index 67f4aeada..173677dbd 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,15 @@ if (!globalThis.fetch) { } ``` +`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. + +Alternatively, 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)); +``` + ## Upgrading Using an old version of node-fetch? Check out the following files: diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 10d38927f..efa2e1b4e 100644 --- a/docs/CHANGELOG.md +++ b/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 diff --git a/docs/v3-UPGRADE-GUIDE.md b/docs/v3-UPGRADE-GUIDE.md index 70120adc6..4e9eada0f 100644 --- a/docs/v3-UPGRADE-GUIDE.md +++ b/docs/v3-UPGRADE-GUIDE.md @@ -19,17 +19,29 @@ 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`. +`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. + +Alternatively, 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)); +``` ## 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 +69,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 +83,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.