- -
A light-weight module that brings Fetch API to Node.js.
-
- 
- 
- 
- 
- -
- Consider supporting us on our Open Collective: -
-
-
-
- A light-weight module that brings Fetch API to Node.js.
-
-
-
-
-
-
-Promise<[Response](#class-response)>
-
-Perform an HTTP(S) fetch.
-
-`url` should be an absolute URL, such as `https://example.com/`. A path-relative URL (`/file/under/root`) or protocol-relative URL (`//can-be-http-or-https.com/`) will result in a rejected `Promise`.
-
-
-
-### Options
-
-The default values are shown after each option key.
-
-```js
-{
- // These properties are part of the Fetch Standard
- method: 'GET',
- headers: {}, // Request headers. format is the identical to that accepted by the Headers constructor (see below)
- body: null, // Request body. can be null, or a Node.js Readable stream
- redirect: 'follow', // Set to `manual` to extract redirect headers, `error` to reject redirect
- signal: null, // Pass an instance of AbortSignal to optionally abort requests
-
- // The following properties are node-fetch extensions
- follow: 20, // maximum redirect count. 0 to not follow redirect
- compress: true, // support gzip/deflate content encoding. false to disable
- size: 0, // maximum response body size in bytes. 0 to disable
- agent: null, // http(s).Agent instance or function that returns an instance (see below)
- highWaterMark: 16384, // the maximum number of bytes to store in the internal buffer before ceasing to read from the underlying resource.
- insecureHTTPParser: false // Use an insecure HTTP parser that accepts invalid HTTP headers when `true`.
-}
-```
-
-#### Default Headers
-
-If no values are set, the following request headers will be sent automatically:
-
-| Header | Value |
-| ------------------- | ------------------------------------------------------ |
-| `Accept-Encoding` | `gzip, deflate, br` (when `options.compress === true`) |
-| `Accept` | `*/*` |
-| `Content-Length` | _(automatically calculated, if possible)_ |
-| `Host` | _(host and port information from the target URI)_ |
-| `Transfer-Encoding` | `chunked` _(when `req.body` is a stream)_ |
-| `User-Agent` | `node-fetch` |
-
-
-Note: when `body` is a `Stream`, `Content-Length` is not set automatically.
-
-#### Custom Agent
-
-The `agent` option allows you to specify networking related options which are out of the scope of Fetch, including and not limited to the following:
-
-- Support self-signed certificate
-- Use only IPv4 or IPv6
-- Custom DNS Lookup
-
-See [`http.Agent`](https://nodejs.org/api/http.html#http_new_agent_options) for more information.
-
-If no agent is specified, the default agent provided by Node.js is used. Note that [this changed in Node.js 19](https://github.com/nodejs/node/blob/4267b92604ad78584244488e7f7508a690cb80d0/lib/_http_agent.js#L564) to have `keepalive` true by default. If you wish to enable `keepalive` in an earlier version of Node.js, you can override the agent as per the following code sample.
-
-In addition, the `agent` option accepts a function that returns `http`(s)`.Agent` instance given current [URL](https://nodejs.org/api/url.html), this is useful during a redirection chain across HTTP and HTTPS protocol.
-
-```js
-import http from 'node:http';
-import https from 'node:https';
-
-const httpAgent = new http.Agent({
- keepAlive: true
-});
-const httpsAgent = new https.Agent({
- keepAlive: true
-});
-
-const options = {
- agent: function(_parsedURL) {
- if (_parsedURL.protocol == 'http:') {
- return httpAgent;
- } else {
- return httpsAgent;
- }
- }
-};
-```
-
-
-
-#### Custom highWaterMark
-
-Stream on Node.js have a smaller internal buffer size (16kB, aka `highWaterMark`) from client-side browsers (>1MB, not consistent across browsers). Because of that, when you are writing an isomorphic app and using `res.clone()`, it will hang with large response in Node.
-
-The recommended way to fix this problem is to resolve cloned response in parallel:
-
-```js
-import fetch from 'node-fetch';
-
-const response = await fetch('https://example.com');
-const r1 = response.clone();
-
-const results = await Promise.all([response.json(), r1.text()]);
-
-console.log(results[0]);
-console.log(results[1]);
-```
-
-If for some reason you don't like the solution above, since `3.x` you are able to modify the `highWaterMark` option:
-
-```js
-import fetch from 'node-fetch';
-
-const response = await fetch('https://example.com', {
- // About 1MB
- highWaterMark: 1024 * 1024
-});
-
-const result = await res.clone().arrayBuffer();
-console.dir(result);
-```
-
-#### Insecure HTTP Parser
-
-Passed through to the `insecureHTTPParser` option on http(s).request. See [`http.request`](https://nodejs.org/api/http.html#http_http_request_url_options_callback) for more information.
-
-#### Manual Redirect
-
-The `redirect: 'manual'` option for node-fetch is different from the browser & specification, which
-results in an [opaque-redirect filtered response](https://fetch.spec.whatwg.org/#concept-filtered-response-opaque-redirect).
-node-fetch gives you the typical [basic filtered response](https://fetch.spec.whatwg.org/#concept-filtered-response-basic) instead.
-
-```js
-import fetch from 'node-fetch';
-
-const response = await fetch('https://httpbin.org/status/301', { redirect: 'manual' });
-
-if (response.status === 301 || response.status === 302) {
- const locationURL = new URL(response.headers.get('location'), response.url);
- const response2 = await fetch(locationURL, { redirect: 'manual' });
- console.dir(response2);
-}
-```
-
-
-
-### Class: Request
-
-An HTTP(S) request containing information about URL, method, headers, and the body. This class implements the [Body](#iface-body) interface.
-
-Due to the nature of Node.js, the following properties are not implemented at this moment:
-
-- `type`
-- `destination`
-- `mode`
-- `credentials`
-- `cache`
-- `integrity`
-- `keepalive`
-
-The following node-fetch extension properties are provided:
-
-- `follow`
-- `compress`
-- `counter`
-- `agent`
-- `highWaterMark`
-
-See [options](#fetch-options) for exact meaning of these extensions.
-
-#### new Request(input[, options])
-
-_(spec-compliant)_
-
-- `input` A string representing a URL, or another `Request` (which will be cloned)
-- `options` [Options](#fetch-options) for the HTTP(S) request
-
-Constructs a new `Request` object. The constructor is identical to that in the [browser](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request).
-
-In most cases, directly `fetch(url, options)` is simpler than creating a `Request` object.
-
-
-
-### Class: Response
-
-An HTTP(S) response. This class implements the [Body](#iface-body) interface.
-
-The following properties are not implemented in node-fetch at this moment:
-
-- `trailer`
-
-#### new Response([body[, options]])
-
-_(spec-compliant)_
-
-- `body` A `String` or [`Readable` stream][node-readable]
-- `options` A [`ResponseInit`][response-init] options dictionary
-
-Constructs a new `Response` object. The constructor is identical to that in the [browser](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response).
-
-Because Node.js does not implement service workers (for which this class was designed), one rarely has to construct a `Response` directly.
-
-#### response.ok
-
-_(spec-compliant)_
-
-Convenience property representing if the request ended normally. Will evaluate to true if the response status was greater than or equal to 200 but smaller than 300.
-
-#### response.redirected
-
-_(spec-compliant)_
-
-Convenience property representing if the request has been redirected at least once. Will evaluate to true if the internal redirect counter is greater than 0.
-
-#### response.type
-
-_(deviation from spec)_
-
-Convenience property representing the response's type. node-fetch only supports `'default'` and `'error'` and does not make use of [filtered responses](https://fetch.spec.whatwg.org/#concept-filtered-response).
-
-
-
-### Class: Headers
-
-This class allows manipulating and iterating over a set of HTTP headers. All methods specified in the [Fetch Standard][whatwg-fetch] are implemented.
-
-#### new Headers([init])
-
-_(spec-compliant)_
-
-- `init` Optional argument to pre-fill the `Headers` object
-
-Construct a new `Headers` object. `init` can be either `null`, a `Headers` object, an key-value map object or any iterable object.
-
-```js
-// Example adapted from https://fetch.spec.whatwg.org/#example-headers-class
-import {Headers} from 'node-fetch';
-
-const meta = {
- 'Content-Type': 'text/xml'
-};
-const headers = new Headers(meta);
-
-// The above is equivalent to
-const meta = [['Content-Type', 'text/xml']];
-const headers = new Headers(meta);
-
-// You can in fact use any iterable objects, like a Map or even another Headers
-const meta = new Map();
-meta.set('Content-Type', 'text/xml');
-const headers = new Headers(meta);
-const copyOfHeaders = new Headers(headers);
-```
-
-
-
-### Interface: Body
-
-`Body` is an abstract interface with methods that are applicable to both `Request` and `Response` classes.
-
-#### body.body
-
-_(deviation from spec)_
-
-- Node.js [`Readable` stream][node-readable]
-
-Data are encapsulated in the `Body` object. Note that while the [Fetch Standard][whatwg-fetch] requires the property to always be a WHATWG `ReadableStream`, in node-fetch it is a Node.js [`Readable` stream][node-readable].
-
-#### body.bodyUsed
-
-_(spec-compliant)_
-
-- `Boolean`
-
-A boolean property for if this body has been consumed. Per the specs, a consumed body cannot be used again.
-
-#### body.arrayBuffer()
-
-#### body.formData()
-
-#### body.blob()
-
-#### body.json()
-
-#### body.text()
-
-`fetch` comes with methods to parse `multipart/form-data` payloads as well as
-`x-www-form-urlencoded` bodies using `.formData()` this comes from the idea that
-Service Worker can intercept such messages before it's sent to the server to
-alter them. This is useful for anybody building a server so you can use it to
-parse & consume payloads.
-
-