node-fetch

library3.3.2jsnpmunverified

Node-Fetch brings the Web Fetch API to Node.js, providing a familiar interface for making HTTP requests in a Node.js environment. The current stable version is 3.3.2. Both the v3 (ESM-only) and v2 (CommonJS) branches are actively maintained, receiving regular bug fixes and occasional new features.

http-networking

npm install node-fetch

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-FETCH

node-fetch

http-networkingjavascriptv3.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fetch

✓ import fetch from 'node-fetch';

✗ const fetch = require('node-fetch');

Node-Fetch v3 is ESM-only and requires import syntax. For v2, use require.

Headers

✓ import { Headers } from 'node-fetch';

Request

✓ import { Request } from 'node-fetch';

Response

✓ import { Response } from 'node-fetch';

AbortController

✓ import { AbortController } from 'node-fetch';

AbortError

✓ import { AbortError } from 'node-fetch';

This example demonstrates how to make a basic GET request to an external API and parse the JSON response. It also includes error handling for network issues and non-OK HTTP statuses.

import fetch from 'node-fetch'; async function getTodoItem() { try { const response = await fetch('https://jsonplaceholder.typicode.com/todos/1'); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); console.log('Fetched TODO item:', data); } catch (error) { console.error('Error fetching data:', error); } } getTodoItem();

Debug

Known issues

breakingNode-Fetch v3 is an ECMAScript Module (ESM) and does not support CommonJS `require()` syntax directly. If you are in a CommonJS project, you must use dynamic `import()` or revert to `node-fetch` v2.

fix

Use `import fetch from 'node-fetch';` in an ESM context (e.g., in a `.mjs` file or a project with `"type": "module"` in `package.json`). For CommonJS, use `const fetch = await import('node-fetch');` (dynamic import) or stick to `node-fetch@2.x`.

affects: >=3.0.0

gotchaUnlike some HTTP clients, `node-fetch` does not automatically throw an error for non-successful HTTP status codes (e.g., 404, 500). You must explicitly check `response.ok` or `response.status`.

fix

After awaiting `fetch`, always check `if (!response.ok) { throw new Error(...) }` before trying to read the body.

affects: >=2.0.0

gotchaThe `Response` body is a stream and can only be consumed once. Attempting to call methods like `response.json()`, `response.text()`, or `response.blob()` multiple times will result in an error.

fix

Store the result of `response.json()` or `response.text()` in a variable if you need to access the body content multiple times, or use `response.clone()` before consuming it.

affects: >=2.0.0

gotcha`node-fetch` (mimicking the browser Fetch API) does not have a built-in timeout option for requests. Long-running requests can hang indefinitely.

fix

Use an `AbortController` to implement request timeouts. Create a controller, set a timeout, and pass the `signal` to the fetch options: `fetch(url, { signal: controller.signal })`.

affects: >=2.0.0

gotchaNode-Fetch v3 officially requires Node.js v16 or greater for full support. Using it on older Node.js versions might lead to unexpected issues, despite what older `engines` fields might imply.

fix

Ensure your project's Node.js version is `16.0.0` or higher. Update your `package.json`'s `engines` field accordingly.

affects: >=3.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `require('node-fetch')` in a project configured for ECMAScript Modules (ESM) or a `.mjs` file when using Node-Fetch v3.

fix

Change `const fetch = require('node-fetch');` to `import fetch from 'node-fetch';`. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extension.

TypeError: Only absolute URLs are supported

Passing a relative URL (e.g., `/api/data`) to `fetch` without providing a base URL or being in a browser-like environment.

fix

Provide a full, absolute URL (e.g., `https://example.com/api/data`) or construct one using `new URL(relativePath, baseUrl)` before passing it to `fetch`.

FetchError: request to http://localhost:3000/api/data failed, reason: connect ECONNREFUSED 127.0.0.1:3000

The server or resource you are trying to reach is not running, is inaccessible, or is blocking the connection.

fix

Verify that the target server is running and accessible at the specified URL and port. Check firewall rules or proxy settings if applicable.

TypeError: Response body stream already consumed

Attempting to call `response.json()`, `response.text()`, `response.blob()`, etc., more than once on the same `Response` object.

fix

Store the result of the first body consumption (e.g., `const data = await response.json();`) into a variable. If you need to read the body in multiple formats or multiple times, use `const clonedResponse = response.clone();` before the first consumption.

FetchError: AbortError: The user aborted a request.

A `fetch` request was cancelled using an `AbortController`'s `signal.abort()` method, often due to a configured timeout or explicit cancellation.

fix

This is often an expected error for timeouts. Catch `AbortError` specifically (e.g., `if (error instanceof AbortError) { console.log('Request timed out'); }`) to handle it gracefully without crashing your application.

Upgrade

Version history

3.3.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/node-fetch/node-fetch ↗

packagehttps://www.npmjs.com/package/node-fetch ↗