Isomorphic Fetch API

Common errors

• TypeError: fetch is not a function

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

  cause 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');`.

Warnings

• gotcha This 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.
• gotcha Isomorphic-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.
• breaking Version 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.

Install

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

Imports

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

  import { fetch } from 'isomorphic-fetch';

  correct:

  const fetch = require('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
  wrong:

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

  correct:

  const { Headers, Request, Response } = require('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.

Quickstart

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