{"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,"search_vec":"'3.0.0':28 'activ':99 'add':42 'aim':134 'altern':118 'api':3,16,136 'approach':108 'automat':110 'avail':113 'avoid':128 'awar':143 'browser':21 'built':71 'cadenc':80 'choic':133 'client':67 'client-sid':66 'consist':137 'construct':48 'contrast':115 'cross':125 'cross-fetch':124 'current':24 'design':132 'develop':100 'differenti':104 'environ':22 'fetch':2,6,15,44,63,76,112,121,126 'fetch-ponyfil':120 'function':45 'github':73 'global':39,114,129,145 'header':50 'isomorph':1,5 'isomorphic-fetch':4 'iter':93 'javascript':9,147 'key':103 'last':85 'leverag':60 'librari':10 'like':49,119 'mainten':96 'major':86 'make':111 'mean':35 'modif':146 'modifi':37 'node':62 'node-fetch':61 'node.js':19 'oper':31,58 'packag':30 'phase':101 'pollut':130 'polyfil':34,77,107 'ponyfil':117,122 'previous':92 'provid':12 'rather':97 'relat':47 'releas':79,89 'request':51 'requir':139 'respons':53 'scope':40 'server':56 'server-sid':55 'side':57,68 'signific':90 'slow':82 'stabl':25 'suggest':94 'user':140 'v3.0.0':88 'version':26,87 'whatwg':14,75","created_at":"2026-04-19T13:36:17.499954+00:00","updated_at":"2026-04-19T13:36:17.499954+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.0.0.0.dev4","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/matthew-andrews/isomorphic-fetch","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/isomorphic-fetch","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}