Registry / http-networking / isomorphic-fetch

isomorphic-fetch

library0.0.0.0.dev4jsnpmunverified

Isomorphic-fetch is a JavaScript library that provides the WHATWG Fetch API for both Node.js and browser environments. Its current stable version is 3.0.0. The package operates as a polyfill, meaning it modifies the global scope to add the `fetch` function and related constructs like `Headers`, `Request`, and `Response`. For server-side operations, it leverages `node-fetch`, while for client-side, it's built on GitHub's WHATWG Fetch polyfill. Its release cadence has slowed, with the last major version (v3.0.0) released significantly after previous iterations, suggesting a maintenance rather than active development phase. A key differentiator is its polyfill approach, which automatically makes `fetch` available globally, contrasting with 'ponyfill' alternatives like `fetch-ponyfill` or `cross-fetch` that avoid global pollution. This design choice aims for API consistency but requires users to be aware of global modifications.

http-networking

npm install isomorphic-fetch

github ↗package ↗

INSTALL

IMPORT

SIG · ISOMORPHIC-FETCH

isomorphic-fetch

http-networkingjavascriptv0.0.0.0.dev4

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.

Global side effect

✓ require('isomorphic-fetch');

This is the primary way to polyfill the global `fetch`, `Headers`, `Request`, and `Response` APIs in both Node.js and browser environments. The module modifies the global scope upon import.

fetch

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

✗ import { fetch } from 'isomorphic-fetch';

The module's default export is the `fetch` function itself. While `import fetch from 'isomorphic-fetch'` might work with modern bundlers, `require()` is explicitly supported and less ambiguous for this CJS-first package. Using this still triggers the global polyfill.

Headers, Request, Response

✓ const { Headers, Request, Response } = require('isomorphic-fetch');

✗ import { Headers, Request, Response } from 'isomorphic-fetch';

These constructor functions are exposed as named exports, providing access to the underlying Fetch API primitives for advanced use cases, particularly in Node.js. For ESM, the `import` syntax might be supported by bundlers, but CJS `require` is canonical for this package.

Demonstrates basic usage by performing a GET request to an API, handling the response, and logging data or errors.

require('isomorphic-fetch'); fetch('//offline-news-api.herokuapp.com/stories') .then(function(response) { if (response.status >= 400) { throw new Error("Bad response from server"); } return response.json(); }) .then(function(stories) { console.log(stories); }) .catch(function(error) { console.error('Fetch failed:', error); });

Debug

Known issues

gotchaThis package acts as a global polyfill, adding `fetch`, `Headers`, `Request`, and `Response` to the global scope. This can conflict with other polyfills or native browser implementations, leading to unexpected behavior or breakage.

fix

Be mindful of the import order. If global pollution is a concern, consider alternatives like `fetch-ponyfill` or `cross-fetch` which provide the API without modifying the global scope.

affects: >=1.0.0

gotchaIsomorphic-fetch is a polyfill, meaning it will only add `fetch` if it's not already present. If your environment already has a `fetch` implementation (e.g., a newer Node.js version, or a modern browser), `isomorphic-fetch` might not have an effect or could cause subtle inconsistencies depending on its internal checks.

fix

If specific polyfill behavior is required, ensure it loads before any native `fetch` or other polyfills. If a specific version of `fetch` is needed, consider importing `node-fetch` or `github/fetch` directly and managing their scope.

affects: >=1.0.0

breakingVersion 2.0.0 switched its server-side implementation from the GitHub polyfill to `node-fetch`. While generally compatible, subtle differences in behavior, error handling, or stream management between the two underlying libraries could affect existing Node.js applications.

fix

Thoroughly test server-side fetch requests when upgrading from versions prior to 2.0.0. Review `node-fetch` documentation for any specific behaviors you might have relied on in the previous implementation.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: fetch is not a function

`isomorphic-fetch` relies on its import to set the global `fetch` object. This error often occurs if `require('isomorphic-fetch')` is not called, or not called early enough, in your application's lifecycle, or if another library overwrites the global `fetch`.

fix

Ensure `require('isomorphic-fetch');` is placed at the very top of your application's main entry file or within any module that intends to use the global `fetch`. Alternatively, import the `fetch` function directly using `const fetch = require('isomorphic-fetch');`.

ReferenceError: Headers is not defined

While `isomorphic-fetch` polyfills `Headers` and other Fetch API primitives globally, some environments or module bundling configurations might require explicit import or different execution order for these constructors.

fix

Verify that `require('isomorphic-fetch');` has executed. If you need to access `Headers`, `Request`, or `Response` explicitly, import them using named CJS destructuring: `const { Headers, Request, Response } = require('isomorphic-fetch');`.

Upgrade

Version history

0.0.0.0.dev4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/matthew-andrews/isomorphic-fetch ↗

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