{"id":11111,"library":"isomorphic-fetch","title":"Isomorphic Fetch API","description":"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.","status":"maintenance","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/matthew-andrews/isomorphic-fetch","tags":["javascript"],"install":[{"cmd":"npm install isomorphic-fetch","lang":"bash","label":"npm"},{"cmd":"yarn add isomorphic-fetch","lang":"bash","label":"yarn"},{"cmd":"pnpm add isomorphic-fetch","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","symbol":"Global side effect","correct":"require('isomorphic-fetch');"},{"note":"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.","wrong":"import { fetch } from 'isomorphic-fetch';","symbol":"fetch","correct":"const fetch = require('isomorphic-fetch');"},{"note":"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.","wrong":"import { Headers, Request, Response } from 'isomorphic-fetch';","symbol":"Headers, Request, Response","correct":"const { Headers, Request, Response } = require('isomorphic-fetch');"}],"quickstart":{"code":"require('isomorphic-fetch');\n\nfetch('//offline-news-api.herokuapp.com/stories')\n\t.then(function(response) {\n\t\tif (response.status >= 400) {\n\t\t\tthrow new Error(\"Bad response from server\");\n\t\t}\n\t\treturn response.json();\n\t})\n\t.then(function(stories) {\n\t\tconsole.log(stories);\n\t})\n\t.catch(function(error) {\n\t\tconsole.error('Fetch failed:', error);\n\t});\n","lang":"javascript","description":"Demonstrates basic usage by performing a GET request to an API, handling the response, and logging data or errors."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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');`.","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`.","error":"TypeError: fetch is not a function"},{"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');`.","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.","error":"ReferenceError: Headers is not defined"}],"ecosystem":"npm"}