node-fetch — Lightweight Fetch API for Node.js

Introduction

node-fetch brings the browser-standard Fetch API to Node.js, providing a familiar and minimal HTTP client. It follows the WHATWG Fetch specification closely, making it easy to share HTTP logic between server and browser codebases.

What node-fetch Does

• Implements the WHATWG Fetch specification for making HTTP requests in Node.js
• Supports streaming request and response bodies via Node.js Readable streams
• Handles redirects, compression (gzip, deflate, brotli), and custom headers
• Provides AbortController support for request cancellation
• Works as an ESM-first module with backward-compatible CommonJS entry points

Architecture Overview

node-fetch wraps Node.js's built-in http and https modules behind the standard Fetch interface. Incoming responses are wrapped in a Response object with methods like .json(), .text(), and .blob() that match the browser API. The library delegates TLS, keep-alive, and socket pooling to Node.js core, keeping its own codebase lean. Streaming is first-class: response.body is a standard Node.js Readable stream.

Self-Hosting & Configuration

• Install via npm; v3+ is ESM-only, v2 supports CommonJS
• Configure a custom HTTP agent for keep-alive or proxy support
• Set request timeouts via AbortController with setTimeout
• Pass custom headers, methods, and body payloads like the browser Fetch API
• Use with Node.js 18+ built-in fetch or as a polyfill for older versions

Key Features

• Spec-compliant Fetch API surface for server-side JavaScript
• Streaming support for large payloads without buffering the entire response
• Automatic decompression of gzip, deflate, and brotli responses
• AbortController integration for canceling in-flight requests
• Zero external dependencies — relies only on Node.js core modules

Comparison with Similar Tools

• Built-in fetch (Node 18+) — native but only available in newer Node versions; node-fetch covers older LTS releases
• Axios — richer feature set with interceptors and transforms; heavier and uses a different API shape
• got — feature-rich HTTP client with retry, pagination, and hooks; larger API surface
• undici — low-level HTTP/1.1 and HTTP/2 client maintained by the Node.js team; faster but lower-level API

FAQ

Q: Should I use node-fetch or the built-in fetch in Node.js 18+? A: If you only target Node.js 18+, the built-in fetch is sufficient. Use node-fetch for projects supporting older Node.js versions.

Q: How do I handle timeouts? A: Create an AbortController, pass its signal to fetch, and call controller.abort() after a setTimeout delay.

Q: Is node-fetch v3 a breaking change from v2? A: Yes. v3 is ESM-only and drops CommonJS support. Use v2 if your project requires require().

Q: Can I send form data or file uploads? A: Yes. Pass a FormData instance (from the formdata-polyfill or form-data package) as the request body.

Sources

• https://github.com/node-fetch/node-fetch
• https://www.npmjs.com/package/node-fetch