{"id":11114,"library":"isomorphic-unfetch","title":"Isomorphic Fetch API","description":"Isomorphic Unfetch is a lightweight JavaScript library that provides a universal `fetch` API implementation, automatically switching between `unfetch` (a minimal `fetch` ponyfill for browsers) and `node-fetch` (a `fetch` implementation for Node.js) based on the execution environment. The current stable version is 5.0.0. This package aims for a small footprint and consistent behavior across client-side and server-side JavaScript, abstracting away environment-specific `fetch` implementations. It provides both a ponyfill (default named import) and a global polyfill (side-effect import). Recent major updates include the adoption of `node-fetch` v3.x, which mandates Node.js >= 12.20.0, and the addition of first-class TypeScript definitions and Package Exports for improved module resolution. It focuses on simplicity and compatibility with standard `fetch` API usage.","status":"active","version":"4.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/developit/unfetch","tags":["javascript","typescript"],"install":[{"cmd":"npm install isomorphic-unfetch","lang":"bash","label":"npm"},{"cmd":"yarn add isomorphic-unfetch","lang":"bash","label":"yarn"},{"cmd":"pnpm add isomorphic-unfetch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the `fetch` implementation for Node.js environments. Version 3.x is used since `isomorphic-unfetch@4.0.1`, which is ESM-only and requires Node.js >= 12.20.0.","package":"node-fetch","optional":false}],"imports":[{"note":"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.","wrong":"const fetch = require('isomorphic-unfetch');","symbol":"fetch","correct":"import fetch from \"isomorphic-unfetch\";"},{"note":"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`.","wrong":"import fetch from 'isomorphic-unfetch'; // expecting global fetch","symbol":"(polyfill)","correct":"import 'isomorphic-unfetch/polyfill';"},{"note":"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`.","symbol":"fetch (types)","correct":"import type { Request, Response, Headers } from 'isomorphic-unfetch';"}],"quickstart":{"code":"import fetch from \"isomorphic-unfetch\";\nimport type { RequestInit, Response } from 'isomorphic-unfetch';\n\ninterface Post {\n  userId: number;\n  id: number;\n  title: string;\n  body: string;\n}\n\nasync function getExamplePosts(postId: number = 1): Promise<Post | Post[]> {\n  // Use a public API for demonstration\n  const url = `https://jsonplaceholder.typicode.com/posts/${postId}`;\n  const options: RequestInit = {\n    method: 'GET',\n    headers: {\n      'Content-Type': 'application/json',\n      'Accept': 'application/json'\n    },\n    // body: JSON.stringify({ key: 'value' }) // Example for POST/PUT\n  };\n\n  try {\n    const response: Response = await fetch(url, options);\n\n    if (!response.ok) {\n      throw new Error(`HTTP error! Status: ${response.status}`);\n    }\n\n    const data = await response.json();\n    console.log(`Fetched post(s) from ${url}:`, data);\n    return data;\n  } catch (error) {\n    console.error(\"Error fetching data:\", error);\n    throw error;\n  }\n}\n\n// Example usage\ngetExamplePosts(1)\n  .then(() => getExamplePosts(2))\n  .then(() => getExamplePosts()) // Fetch all posts example, though API usually limits\n  .catch(err => console.error(\"An error occurred during quickstart execution:\", err));\n\n// Optional: Global polyfill usage example if you need `fetch` on global scope:\n// import 'isomorphic-unfetch/polyfill';\n// // Now `fetch` is globally available for other parts of your app\n// // For example, `globalThis.fetch` or `window.fetch`","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.1"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure you are using `isomorphic-unfetch` version 3.1.0 or higher to include the `node-fetch` security fix.","message":"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.","severity":"gotcha","affected_versions":"<3.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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')`.","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.","error":"ERR_REQUIRE_ESM"},{"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';`).","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.","error":"ReferenceError: fetch is not defined"},{"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.","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.","error":"TypeError: response.json is not a function"}],"ecosystem":"npm"}