README

A light-weight module that brings Fetch API to Node.js.
	
	
	
	
	
	
	
	
	Consider supporting us on our Open Collective:
	
	
	


---

You might be looking for the v2 docs



- Motivation
- Features
- Difference from client-side fetch
- Installation
- Loading and configuring the module
- Upgrading
- Common Usage
	- Plain text or HTML
	- JSON
	- Simple Post
	- Post with JSON
	- Post with form parameters
	- Handling exceptions
	- Handling client and server errors
	- Handling cookies
- Advanced Usage
	- Streams
	- Accessing Headers and other Metadata
	- Extract Set-Cookie Header
	- Post data using a file
	- Request cancellation with AbortSignal
- API
	- [fetch(url[, options])](fetchurl-options)
	- Options
		- Default Headers
		- Custom Agent
		- Custom highWaterMark
		- Insecure HTTP Parser
	- Class: Request
		- [new Request(input[, options])](new-requestinput-options)
	- Class: Response
		- [new Response([body[, options]])](new-responsebody-options)
		- response.ok
		- response.redirected
		- response.type
	- Class: Headers
		- [new Headers([init])](new-headersinit)
	- Interface: Body
		- body.body
		- body.bodyUsed
		- body.arrayBuffer()
		- body.blob()
		- body.formData()
		- body.json()
		- body.text()
	- Class: FetchError
	- Class: AbortError
- TypeScript
- Acknowledgement
- Team
				- Former
- License



 Motivation

Instead of implementing XMLHttpRequest in Node.js to run browser-specific Fetch polyfill, why not go from native http to fetch API directly? Hence, node-fetch, minimal code for a window.fetch compatible API on Node.js runtime.

See Jason Miller's isomorphic-unfetch or Leonardo Quixada's cross-fetch for isomorphic usage (exports node-fetch for server-side, whatwg-fetch for client-side).

 Features

- Stay consistent with window.fetch API.
- Make conscious trade-off when following [WHATWG fetch spec][whatwg-fetch] and stream spec implementation details, document known differences.
- Use native promise and async functions.
- Use native Node streams for body, on both request and response.
- Decode content encoding (gzip/deflate/brotli) properly, and convert string output (such as res.text() and res.json()) to UTF-8 automatically.
- Useful extensions such as redirect limit, response size limit, [explicit errors][error-handling.md] for troubleshooting.

 Difference from client-side fetch

- See known differences:
	- As of v3.x
	- As of v2.x
- If you happen to use a missing feature that window.fetch offers, feel free to open an issue.
- Pull requests are welcomed too!

 Installation

Current stable release (3.x) requires at least Node.js 12.20.0.

sh
npm install node-fetch


 Loading and configuring the module

 ES Modules (ESM)

js
import fetch from 'node-fetch';


 CommonJS

node-fetch from v3 is an ESM-only module - you are not able to import it with require().

If you cannot switch to ESM, please use v2 which remains compatible with CommonJS. Critical bug fixes will continue to be published for v2.

sh
npm install node-fetch@2


Altern