node-fetch

node-fetch brings the familiar window.fetch() API to Node.js so server-side code can make HTTP requests using the same Promise-based, Request/Response-shaped interface browsers use. It talks directly to Node’s native http and https modules rather than wrapping another HTTP client, and handles gzip/deflate/brotli decompression, redirects, streaming bodies, and AbortController-based cancellation out of the box.

Because it mirrors the WHATWG Fetch spec closely, code written against node-fetch reads almost identically to browser fetch calls, which makes isomorphic (shared client/server) HTTP code easier to write and makes onboarding trivial for anyone who already knows fetch().

What You Get

• A fetch() function with the same signature and Promise-based Response as browser fetch()
• Request, Response, and Headers classes that mirror the WHATWG Fetch spec
• Automatic gzip/deflate/brotli response decompression via node:zlib
• Streaming request/response bodies backed by native Node streams
• AbortController/AbortSignal support for request cancellation
• Built-in support for data: URLs, Blob/File, and FormData (multipart) bodies

Common Use Cases

• Calling third-party REST APIs from a Node.js backend without adding a heavyweight HTTP client dependency
• Writing isomorphic utility code that runs unchanged in the browser and on the server
• Proxying or relaying HTTP requests/responses (e.g. streaming a remote file straight to disk or to a client)
• Server-side rendering or build tooling that needs to fetch remote data during a Node.js process

Under The Hood

Architecture

node-fetch implements the WHATWG Fetch API surface as ES modules under src/: index.js orchestrates the request/response lifecycle (redirect following, gzip/deflate/brotli decompression via node:zlib, abort-signal handling), delegating to request.js (builds Node http/https request options from a Fetch-spec-shaped Request class), response.js (wraps Node’s IncomingMessage stream), body.js (a shared Body mixin implementing text()/json()/arrayBuffer()/formData() over Node streams), and headers.js (a case-insensitive Headers implementation). Supporting utils/ modules handle referrer-policy resolution, redirect-status detection, and multipart form parsing, keeping cross-cutting spec logic out of the core orchestrator.

Tech Stack

Pure JavaScript (98%) with a small hand-written TypeScript typings file (@types/index.d.ts), published as an ESM-only package (“type”: “module”) targeting Node >=12.20.0/14.13.1/16+. Runtime dependencies are minimal and single-purpose — data-uri-to-buffer for data: URL support, fetch-blob for Blob/File, and formdata-polyfill for FormData — with no transitive HTTP client dependency, since it talks directly to node:http/https. Dev tooling uses mocha + c8 for tests/coverage, xo (an ESLint preset) for linting, and tsd for type-testing.

Code Quality

The test/ directory has 9 files (a large spec-conformance suite in main.js alongside headers.js, request.js, response.js, form-data.js, referrer.js, and external-encoding.js) run via mocha with c8 coverage reported to Coveralls, indicating deliberate, spec-driven test coverage rather than an afterthought. Error handling is centralized in src/errors/ with dedicated FetchError and AbortError classes rather than generic throws, and naming/structure closely track WHATWG Fetch terminology (Request, Response, Headers, Body), keeping the mental model aligned with browser fetch. Recent GitHub activity is low and maintenance has become infrequent, so code quality remains high but the project is no longer evolving quickly.

API Design node-fetch is designed as a drop-in for the browser fetch() signature — fetch(url, options) returning a Promise<Response> — so most developers can use it with zero new concepts. It re-exports Request, Response, Headers, FormData, Blob/File, and its error classes for parity with browser code, and it documents differences from client-side fetch explicitly (docs/v3-LIMITS.md) rather than leaving them for users to discover. The README is extensive, covering streams, cookies, custom agents, and TypeScript usage, which lowers the adoption barrier, though the ESM-only requirement introduced in v3 is a real migration/DX friction point for CommonJS consumers.