![\"Node](\"docs/media/Banner.svg\")
\n\t\n\t
A light-weight module that brings Fetch API to Node.js.
\n\t![\"Build](\"https://github.com/node-fetch/node-fetch/workflows/CI/badge.svg?branch=master\"){kind=icon}
\n\t![\"Coverage](\"https://img.shields.io/coveralls/github/node-fetch/node-fetch\")
\n\t![\"Install](\"https://img.shields.io/npm/v/node-fetch\")
\n\t![\"Mentioned](\"https://awesome.re/mentioned-badge.svg\"){kind=icon}
\n\t![\"Discord\"](\"https://img.shields.io/discord/619915844268326952?color=%237289DA&label=Discord\")
\n\t\n\t
\n\tConsider supporting us on our Open Collective:\n\t
\n\t
\n\t
![\"Open](\"https://opencollective.com/node-fetch/donate/button.png?color=blue\")
\n\n\tA light-weight module that brings Fetch API to Node.js.
\n\t\n\t\n\t\n\t\n\t\n\t\nPromise<[Response](#class-response)>\n\nPerform an HTTP(S) fetch.\n\n`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`.\n\n\n\n### Options\n\nThe default values are shown after each option key.\n\n```js\n{\n\t// These properties are part of the Fetch Standard\n\tmethod: 'GET',\n\theaders: {}, // Request headers. format is the identical to that accepted by the Headers constructor (see below)\n\tbody: null, // Request body. can be null, a string, a Buffer, a Blob, or a Node.js Readable stream\n\tredirect: 'follow', // Set to `manual` to extract redirect headers, `error` to reject redirect\n\tsignal: null, // Pass an instance of AbortSignal to optionally abort requests\n\n\t// The following properties are node-fetch extensions\n\tfollow: 20, // maximum redirect count. 0 to not follow redirect\n\tcompress: true, // support gzip/deflate content encoding. false to disable\n\tsize: 0, // maximum response body size in bytes. 0 to disable\n\tagent: null, // http(s).Agent instance or function that returns an instance (see below)\n\thighWaterMark: 16384, // the maximum number of bytes to store in the internal buffer before ceasing to read from the underlying resource.\n\tinsecureHTTPParser: false\t// Use an insecure HTTP parser that accepts invalid HTTP headers when `true`.\n}\n```\n\n#### Default Headers\n\nIf no values are set, the following request headers will be sent automatically:\n\n| Header | Value |\n| ------------------- | ------------------------------------------------------ |\n| `Accept-Encoding` | `gzip,deflate,br` _(when `options.compress === true`)_ |\n| `Accept` | `*/*` |\n| `Connection` | `close` _(when no `options.agent` is present)_ |\n| `Content-Length` | _(automatically calculated, if possible)_ |\n| `Transfer-Encoding` | `chunked` _(when `req.body` is a stream)_ |\n| `User-Agent` | `node-fetch` |\n\n\nNote: when `body` is a `Stream`, `Content-Length` is not set automatically.\n\n#### Custom Agent\n\nThe `agent` option allows you to specify networking related options which are out of the scope of Fetch, including and not limited to the following:\n\n- Support self-signed certificate\n- Use only IPv4 or IPv6\n- Custom DNS Lookup\n\nSee [`http.Agent`](https://nodejs.org/api/http.html#http_new_agent_options) for more information.\n\nIn 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.\n\n```js\nconst http = require('http');\nconst https = require('https');\n\nconst httpAgent = new http.Agent({\n\tkeepAlive: true\n});\nconst httpsAgent = new https.Agent({\n\tkeepAlive: true\n});\n\nconst options = {\n\tagent: function(_parsedURL) {\n\t\tif (_parsedURL.protocol == 'http:') {\n\t\t\treturn httpAgent;\n\t\t} else {\n\t\t\treturn httpsAgent;\n\t\t}\n\t}\n};\n```\n\n\n\n#### Custom highWaterMark\n\nStream 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.\n\nThe recommended way to fix this problem is to resolve cloned response in parallel:\n\n```js\nconst fetch = require('node-fetch');\n\nconst response = await fetch('https://example.com');\nconst r1 = await response.clone();\n\nconst results = await Promise.all([response.json(), r1.text()]);\n\nconsole.log(results[0]);\nconsole.log(results[1]);\n```\n\nIf for some reason you don't like the solution above, since `3.x` you are able to modify the `highWaterMark` option:\n\n```js\nconst fetch = require('node-fetch');\n\nconst response = await fetch('https://example.com', {\n\t// About 1MB\n\thighWaterMark: 1024 * 1024\n});\n\nconst result = await res.clone().buffer();\nconsole.dir(result);\n```\n\n#### Insecure HTTP Parser\n\nPassed 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.\n\n\n\n\n### Class: Request\n\nAn HTTP(S) request containing information about URL, method, headers, and the body. This class implements the [Body](#iface-body) interface.\n\nDue to the nature of Node.js, the following properties are not implemented at this moment:\n\n- `type`\n- `destination`\n- `referrer`\n- `referrerPolicy`\n- `mode`\n- `credentials`\n- `cache`\n- `integrity`\n- `keepalive`\n\nThe following node-fetch extension properties are provided:\n\n- `follow`\n- `compress`\n- `counter`\n- `agent`\n- `highWaterMark`\n\nSee [options](#fetch-options) for exact meaning of these extensions.\n\n#### new Request(input[, options])\n\n_(spec-compliant)_\n\n- `input` A string representing a URL, or another `Request` (which will be cloned)\n- `options` [Options][#fetch-options] for the HTTP(S) request\n\nConstructs a new `Request` object. The constructor is identical to that in the [browser](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request).\n\nIn most cases, directly `fetch(url, options)` is simpler than creating a `Request` object.\n\n\n\n### Class: Response\n\nAn HTTP(S) response. This class implements the [Body](#iface-body) interface.\n\nThe following properties are not implemented in node-fetch at this moment:\n\n- `trailer`\n\n#### new Response([body[, options]])\n\n_(spec-compliant)_\n\n- `body` A `String` or [`Readable` stream][node-readable]\n- `options` A [`ResponseInit`][response-init] options dictionary\n\nConstructs a new `Response` object. The constructor is identical to that in the [browser](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response).\n\nBecause Node.js does not implement service workers (for which this class was designed), one rarely has to construct a `Response` directly.\n\n#### response.ok\n\n_(spec-compliant)_\n\nConvenience 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.\n\n#### response.redirected\n\n_(spec-compliant)_\n\nConvenience property representing if the request has been redirected at least once. Will evaluate to true if the internal redirect counter is greater than 0.\n\n#### response.type\n\n_(deviation from spec)_\n\nConvenience 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).\n\n\n\n### Class: Headers\n\nThis class allows manipulating and iterating over a set of HTTP headers. All methods specified in the [Fetch Standard][whatwg-fetch] are implemented.\n\n#### new Headers([init])\n\n_(spec-compliant)_\n\n- `init` Optional argument to pre-fill the `Headers` object\n\nConstruct a new `Headers` object. `init` can be either `null`, a `Headers` object, an key-value map object or any iterable object.\n\n```js\n// Example adapted from https://fetch.spec.whatwg.org/#example-headers-class\nconst {Headers} = require('node-fetch');\n\nconst meta = {\n\t'Content-Type': 'text/xml',\n\t'Breaking-Bad': '<3'\n};\nconst headers = new Headers(meta);\n\n// The above is equivalent to\nconst meta = [['Content-Type', 'text/xml'], ['Breaking-Bad', '<3']];\nconst headers = new Headers(meta);\n\n// You can in fact use any iterable objects, like a Map or even another Headers\nconst meta = new Map();\nmeta.set('Content-Type', 'text/xml');\nmeta.set('Breaking-Bad', '<3');\nconst headers = new Headers(meta);\nconst copyOfHeaders = new Headers(headers);\n```\n\n\n\n### Interface: Body\n\n`Body` is an abstract interface with methods that are applicable to both `Request` and `Response` classes.\n\nThe following methods are not yet implemented in node-fetch at this moment:\n\n- `formData()`\n\n#### body.body\n\n_(deviation from spec)_\n\n- Node.js [`Readable` stream][node-readable]\n\nData 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].\n\n#### body.bodyUsed\n\n_(spec-compliant)_\n\n- `Boolean`\n\nA boolean property for if this body has been consumed. Per the specs, a consumed body cannot be used again.\n\n#### body.arrayBuffer()\n\n#### body.blob()\n\n#### body.json()\n\n#### body.text()\n\n_(spec-compliant)_\n\n- Returns: `Promise`\n\nConsume the body and return a promise that will resolve to one of these formats.\n\n#### body.buffer()\n\n_(node-fetch extension)_\n\n- Returns: `Promise