Registry / http-networking / isomorphic-unfetch

isomorphic-unfetch

library4.0.2jsnpmunverified

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.

http-networking

npm install isomorphic-unfetch

github ↗package ↗

INSTALL

IMPORT

SIG · ISOMORPHIC-UNFETCH

isomorphic-unfetch

http-networkingjavascriptv4.0.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 "isomorphic-unfetch";

✗ const fetch = require('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)

✓ import 'isomorphic-unfetch/polyfill';

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

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

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`

Debug

Known issues

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

affects: >=4.0.1

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

affects: >=4.0.0

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

affects: >=5.0.0

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

affects: <3.1.0

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

affects: <4.2.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

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

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

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.

Upgrade

Version history

4.0.2latest on npm

Audit

Dependencies

node-fetchrequiredProvides 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.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/developit/unfetch ↗

packagehttps://www.npmjs.com/package/isomorphic-unfetch ↗