cross-fetch: Universal WHATWG Fetch

Common errors

• TypeError: fetch is not a function

  cause 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.

  cause 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'.

  cause 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`.

Warnings

• breaking cross-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.
• gotcha Minor 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.
• gotcha The 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.

Install

• npm install cross-fetch npm
• yarn add cross-fetch yarn
• pnpm add cross-fetch pnpm

Imports

• fetch
  wrong:

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

  correct:

  import { fetch } from 'cross-fetch';

  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
  wrong:

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

  correct:

  import { Headers } from 'cross-fetch';

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

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

  correct:

  import { Request } from 'cross-fetch';

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

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

  correct:

  import { Response } from 'cross-fetch';

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

Quickstart

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();