Registry / http-networking / cross-fetch

cross-fetch

library4.1.0jsnpmunverified

cross-fetch provides a universal implementation of the WHATWG Fetch API, making it available consistently across Node.js, modern web browsers, and React Native environments. It currently maintains version 4.1.0 and is actively developed, with frequent patch and minor releases, alongside major version updates to support new Node.js runtimes and integrate updates from its underlying `node-fetch` and `whatwg-fetch` dependencies. Its primary differentiator is simplifying HTTP requests by abstracting away environment-specific `fetch` implementations, allowing developers to write isomorphic code without conditional imports or manual polyfill management. This ensures that `fetch` behaves predictably whether executed server-side or client-side, addressing common challenges in full-stack JavaScript applications.

http-networking web-framework

npm install cross-fetch

github ↗package ↗

INSTALL

IMPORT

SIG · CROSS-FETCH

cross-fetch

http-networkingjavascriptv4.1.0

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 'cross-fetch';

✗ import fetch from 'cross-fetch'; // Named import is preferred as of v3+ const fetch = require('cross-fetch'); // This works, but prefer destructuring

For direct usage, named import is the standard. The library exports `fetch` as a named export from v3 onwards. For CJS, destructuring `require` is recommended.

Headers

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

✗ const Headers = require('cross-fetch').Headers;

Access to `Headers`, `Request`, and `Response` constructors is available via named imports for consistency with the Fetch API specification.

Request

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

✗ import { fetch, Request } from 'cross-fetch/dist/node-ponyfill'; // Incorrect path, direct from 'cross-fetch' is universal

The `Request` constructor is directly exported from the main package entry point for universal use.

Response

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

✗ import { Response } from 'node-fetch'; // If explicitly trying to use the underlying Node.js implementation without cross-fetch's universal layer.

The `Response` constructor is also directly exported, providing a consistent API surface across environments.

This quickstart demonstrates how to perform both GET and POST requests using `cross-fetch` in an asynchronous function, including basic error handling.

import { fetch } from 'cross-fetch'; async function fetchData() { 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 data:', data); // Example with POST request const postResponse = await fetch('https://jsonplaceholder.typicode.com/posts', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ title: 'foo', body: 'bar', userId: 1, }), }); if (!postResponse.ok) { throw new Error(`HTTP error! status: ${postResponse.status}`); } const postData = await postResponse.json(); console.log('Posted data:', postData); } catch (error) { console.error('Error fetching data:', error); } } fetchData();

Debug

Known issues

breakingcross-fetch v4.0.0 dropped official support for Node.js versions 10 and 12. While it might still function, tests are no longer run against these versions, and no support is provided for issues arising on them.

fix

Upgrade your Node.js runtime to version 14 or higher. Node.js 18 or 20 are explicitly supported in v4.0.0, and Node 22 in v4.1.0.

affects: >=4.0.0

gotchaMinor versions of cross-fetch (e.g., v3.2.0, v4.1.0) frequently update their underlying `node-fetch` and `whatwg-fetch` dependencies. This can introduce subtle behavioral changes or new features/bugs inherited from these upstream libraries, which might not be explicitly detailed in `cross-fetch` release notes.

fix

Always review the release notes of `node-fetch` and `whatwg-fetch` for the versions being upgraded when updating `cross-fetch` to understand potential impacts on your application's network requests.

affects: >=3.2.0

gotchaThe v4.0.0 release noted potential 'implementation conflicts in the Fetch API tests'. While `cross-fetch` aims for WHATWG spec compliance, differences between `node-fetch` and `whatwg-fetch` or their specific versions could lead to edge-case behavioral discrepancies.

fix

Thoroughly test network-intensive parts of your application after upgrading to v4.0.0 or later, paying close attention to header handling, redirects, and error conditions, especially if relying on specific Fetch API nuances.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: fetch is not a function

Attempting to use `fetch` without proper import or in an environment where `cross-fetch` has not been initialized or globally polyfilled.

fix

Ensure you are using `import { fetch } from 'cross-fetch';` in ESM or `const { fetch } = require('cross-fetch');` in CJS. Alternatively, for global polyfilling, `import 'cross-fetch/polyfill';` (or `require('cross-fetch/polyfill');`) should be at the entry point of your application.

TS2307: Cannot find module 'cross-fetch' or its corresponding type declarations.

TypeScript compiler cannot locate the type definitions for `cross-fetch`.

fix

Ensure `cross-fetch` is installed correctly. If using an older TypeScript version or specific configuration, verify `tsconfig.json` includes `node_modules/@types` in `typeRoots` and `cross-fetch` is not excluded. Types are shipped with the package itself, so `@types/cross-fetch` is not typically needed.

Property 'json' does not exist on type 'Response'.

This error typically indicates an issue with TypeScript's understanding of the `Response` object, often related to global `lib.dom.d.ts` conflicting or not being properly augmented by `cross-fetch`'s types, especially in earlier versions.

fix

Upgrade `cross-fetch` to the latest version (e.g., v3.1.2+ addressed similar issues). Ensure your `tsconfig.json` includes `lib` entries appropriate for `dom` if in a browser-like environment, and `esnext`.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

node-fetchrequiredProvides the Fetch API implementation for Node.js environments.

whatwg-fetchrequiredProvides the Fetch API polyfill for older browser environments and React Native.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lquixada/cross-fetch ↗

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