Isomorphic Fetch API

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to `require()` `isomorphic-unfetch` in a Node.js environment with an older version of Node.js (prior to 12.20.0) or when `node-fetch` 3.x's ESM nature causes conflicts with CJS contexts.
  fix Upgrade Node.js to version 12.20.0 or newer. If still encountering issues, ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) or use dynamic `import('isomorphic-unfetch')`.

• ReferenceError: fetch is not defined

  cause Using `isomorphic-unfetch` version 4.0.0 or later as a ponyfill without explicitly assigning the imported `fetch` function or importing the polyfill entry point.
  fix Either import the `fetch` function explicitly (e.g., `import fetch from 'isomorphic-unfetch';`) and use it, or import the polyfill for global availability (`import 'isomorphic-unfetch/polyfill';`).

• TypeError: response.json is not a function

  cause Misunderstanding that `response.json()` returns a Promise, not the parsed JSON directly, or issues with an invalid response body not being parsable as JSON.
  fix Always `await` `response.json()` or use `.then()` on it, for example: `const data = await response.json();`. Ensure the server response actually contains valid JSON.

Warnings

• breaking Starting with `isomorphic-unfetch@4.0.1`, the underlying `node-fetch` dependency was upgraded to v3.x. This version of `node-fetch` is ESM-only and requires Node.js version >= 12.20.0. Applications running on older Node.js versions will encounter errors.
  Fix: Upgrade your Node.js environment to version 12.20.0 or higher, or downgrade `isomorphic-unfetch` to a version prior to 4.0.1.
• breaking In `unfetch@4.0.0` (which `isomorphic-unfetch` bundles), the default `import fetch from 'unfetch'` (or `isomorphic-unfetch`) changed from being a global polyfill to a ponyfill. This means `fetch` is no longer automatically installed on `window` or `global` unless explicitly imported via the polyfill entry point.
  Fix: If you relied on `fetch` being globally available, switch your import from `import fetch from 'isomorphic-unfetch'` to `import 'isomorphic-unfetch/polyfill';` (for side effects) or explicitly assign the imported `fetch` to `globalThis.fetch`.
• breaking Version 5.0.0 introduced Package Exports for better module resolution, and officially added TypeScript definitions. While improving compatibility, this might affect custom build configurations or tools that do not fully support `exports` maps in `package.json`.
  Fix: Ensure your build tools (e.g., webpack, rollup, TypeScript, Node.js runtime) are updated to versions that correctly handle `package.json` `exports` fields. Update TypeScript to benefit from the new definitions.
• gotcha A security fix for `node-fetch` was included in `isomorphic-unfetch@3.1.0`. While specific details are not provided in the changelog, it is generally recommended to upgrade to this version or newer to incorporate any critical security patches.
  Fix: Ensure you are using `isomorphic-unfetch` version 3.1.0 or higher to include the `node-fetch` security fix.
• gotcha Prior to `unfetch@4.2.0`, `.json()` parse errors would throw synchronously. After this version, they return a rejected Promise, aligning with standard `fetch` behavior.
  Fix: Update to `isomorphic-unfetch@4.2.0` or higher to ensure `.json()` parse errors are handled as rejected Promises, allowing for consistent `try/catch` or `.catch()` error handling.

Install

• npm install isomorphic-unfetch npm
• yarn add isomorphic-unfetch yarn
• pnpm add isomorphic-unfetch pnpm

Imports

• fetch
  wrong:

  const fetch = require('isomorphic-unfetch');

  correct:

  import fetch from "isomorphic-unfetch";

  Since v4.0.1, the internal `node-fetch` dependency is ESM-only, requiring Node.js >= 12.20.0. While CommonJS `require` still works due to package exports, ESM imports are preferred. In v4.0.0, `unfetch` (which `isomorphic-unfetch` wraps) became a ponyfill by default, meaning `fetch` is not automatically installed globally.
• (polyfill)
  wrong:

  import fetch from 'isomorphic-unfetch'; // expecting global fetch

  correct:

  import 'isomorphic-unfetch/polyfill';

  To globally polyfill `fetch` (i.e., make it available on `window` or `global`), explicitly import the polyfill entry point. This pattern was introduced in `unfetch@4.0.0`.
• fetch (types)

  import type { Request, Response, Headers } from 'isomorphic-unfetch';

  TypeScript definitions were officially added and exported in v5.0.0, providing types for `Request`, `Response`, `Headers`, and other `fetch` API constructs. This also includes `RequestInit` and `ResponseInit`.

Quickstart

Demonstrates how to use `isomorphic-unfetch` as a ponyfill to make `GET` requests, handle responses, and includes basic TypeScript typing for typical `fetch` API usage.

import fetch from "isomorphic-unfetch";
import type { RequestInit, Response } from 'isomorphic-unfetch';

interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

async function getExamplePosts(postId: number = 1): Promise<Post | Post[]> {
  // Use a public API for demonstration
  const url = `https://jsonplaceholder.typicode.com/posts/${postId}`;
  const options: RequestInit = {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    // body: JSON.stringify({ key: 'value' }) // Example for POST/PUT
  };

  try {
    const response: Response = await fetch(url, options);

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    console.log(`Fetched post(s) from ${url}:`, data);
    return data;
  } catch (error) {
    console.error("Error fetching data:", error);
    throw error;
  }
}

// Example usage
getExamplePosts(1)
  .then(() => getExamplePosts(2))
  .then(() => getExamplePosts()) // Fetch all posts example, though API usually limits
  .catch(err => console.error("An error occurred during quickstart execution:", err));

// Optional: Global polyfill usage example if you need `fetch` on global scope:
// import 'isomorphic-unfetch/polyfill';
// // Now `fetch` is globally available for other parts of your app
// // For example, `globalThis.fetch` or `window.fetch`