{"id":10691,"library":"cross-fetch","title":"cross-fetch: Universal WHATWG Fetch","description":"cross-fetch provides a universal implementation of the WHATWG Fetch API, making it available consistently across Node.js, modern web browsers, and React Native environments. It currently maintains version 4.1.0 and is actively developed, with frequent patch and minor releases, alongside major version updates to support new Node.js runtimes and integrate updates from its underlying `node-fetch` and `whatwg-fetch` dependencies. Its primary differentiator is simplifying HTTP requests by abstracting away environment-specific `fetch` implementations, allowing developers to write isomorphic code without conditional imports or manual polyfill management. This ensures that `fetch` behaves predictably whether executed server-side or client-side, addressing common challenges in full-stack JavaScript applications.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/lquixada/cross-fetch","tags":["javascript","fetch","http","url","promise","async","await","isomorphic","universal","typescript"],"install":[{"cmd":"npm install cross-fetch","lang":"bash","label":"npm"},{"cmd":"yarn add cross-fetch","lang":"bash","label":"yarn"},{"cmd":"pnpm add cross-fetch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the Fetch API implementation for Node.js environments.","package":"node-fetch","optional":false},{"reason":"Provides the Fetch API polyfill for older browser environments and React Native.","package":"whatwg-fetch","optional":false}],"imports":[{"note":"For direct usage, named import is the standard. The library exports `fetch` as a named export from v3 onwards. For CJS, destructuring `require` is recommended.","wrong":"import fetch from 'cross-fetch'; // Named import is preferred as of v3+\nconst fetch = require('cross-fetch'); // This works, but prefer destructuring","symbol":"fetch","correct":"import { fetch } from 'cross-fetch';"},{"note":"Access to `Headers`, `Request`, and `Response` constructors is available via named imports for consistency with the Fetch API specification.","wrong":"const Headers = require('cross-fetch').Headers;","symbol":"Headers","correct":"import { Headers } from 'cross-fetch';"},{"note":"The `Request` constructor is directly exported from the main package entry point for universal use.","wrong":"import { fetch, Request } from 'cross-fetch/dist/node-ponyfill'; // Incorrect path, direct from 'cross-fetch' is universal","symbol":"Request","correct":"import { Request } from 'cross-fetch';"},{"note":"The `Response` constructor is also directly exported, providing a consistent API surface across environments.","wrong":"import { Response } from 'node-fetch'; // If explicitly trying to use the underlying Node.js implementation without cross-fetch's universal layer.","symbol":"Response","correct":"import { Response } from 'cross-fetch';"}],"quickstart":{"code":"import { fetch } from 'cross-fetch';\n\nasync function fetchData() {\n  try {\n    const response = await fetch('https://jsonplaceholder.typicode.com/todos/1');\n    if (!response.ok) {\n      throw new Error(`HTTP error! status: ${response.status}`);\n    }\n    const data = await response.json();\n    console.log('Fetched data:', data);\n\n    // Example with POST request\n    const postResponse = await fetch('https://jsonplaceholder.typicode.com/posts', {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n      },\n      body: JSON.stringify({\n        title: 'foo',\n        body: 'bar',\n        userId: 1,\n      }),\n    });\n    if (!postResponse.ok) {\n      throw new Error(`HTTP error! status: ${postResponse.status}`);\n    }\n    const postData = await postResponse.json();\n    console.log('Posted data:', postData);\n\n  } catch (error) {\n    console.error('Error fetching data:', error);\n  }\n}\n\nfetchData();\n","lang":"typescript","description":"This quickstart demonstrates how to perform both GET and POST requests using `cross-fetch` in an asynchronous function, including basic error handling."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 14 or higher. Node.js 18 or 20 are explicitly supported in v4.0.0, and Node 22 in v4.1.0.","message":"cross-fetch v4.0.0 dropped official support for Node.js versions 10 and 12. While it might still function, tests are no longer run against these versions, and no support is provided for issues arising on them.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always review the release notes of `node-fetch` and `whatwg-fetch` for the versions being upgraded when updating `cross-fetch` to understand potential impacts on your application's network requests.","message":"Minor versions of cross-fetch (e.g., v3.2.0, v4.1.0) frequently update their underlying `node-fetch` and `whatwg-fetch` dependencies. This can introduce subtle behavioral changes or new features/bugs inherited from these upstream libraries, which might not be explicitly detailed in `cross-fetch` release notes.","severity":"gotcha","affected_versions":">=3.2.0"},{"fix":"Thoroughly test network-intensive parts of your application after upgrading to v4.0.0 or later, paying close attention to header handling, redirects, and error conditions, especially if relying on specific Fetch API nuances.","message":"The v4.0.0 release noted potential 'implementation conflicts in the Fetch API tests'. While `cross-fetch` aims for WHATWG spec compliance, differences between `node-fetch` and `whatwg-fetch` or their specific versions could lead to edge-case behavioral discrepancies.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { fetch } from 'cross-fetch';` in ESM or `const { fetch } = require('cross-fetch');` in CJS. Alternatively, for global polyfilling, `import 'cross-fetch/polyfill';` (or `require('cross-fetch/polyfill');`) should be at the entry point of your application.","cause":"Attempting to use `fetch` without proper import or in an environment where `cross-fetch` has not been initialized or globally polyfilled.","error":"TypeError: fetch is not a function"},{"fix":"Ensure `cross-fetch` is installed correctly. If using an older TypeScript version or specific configuration, verify `tsconfig.json` includes `node_modules/@types` in `typeRoots` and `cross-fetch` is not excluded. Types are shipped with the package itself, so `@types/cross-fetch` is not typically needed.","cause":"TypeScript compiler cannot locate the type definitions for `cross-fetch`.","error":"TS2307: Cannot find module 'cross-fetch' or its corresponding type declarations."},{"fix":"Upgrade `cross-fetch` to the latest version (e.g., v3.1.2+ addressed similar issues). Ensure your `tsconfig.json` includes `lib` entries appropriate for `dom` if in a browser-like environment, and `esnext`.","cause":"This error typically indicates an issue with TypeScript's understanding of the `Response` object, often related to global `lib.dom.d.ts` conflicting or not being properly augmented by `cross-fetch`'s types, especially in earlier versions.","error":"Property 'json' does not exist on type 'Response'."}],"ecosystem":"npm"}