whatwg-fetch

library3.6.20jsnpmunverified

A lightweight polyfill for the Fetch API, implementing a subset of the standard Fetch specification to replace XMLHttpRequest in web applications. Current stable version is 3.6.20, released on 2023-12-14. This package is the de facto standard for adding fetch support in older browsers; it is actively maintained by the GitHub community and has minimal dependencies. Note that it only works in browser environments, not Node.js, and for very old browsers a separate Promise polyfill is required.

testing

npm install whatwg-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WHATWG-FETCH

whatwg-fetch

testingjavascriptv3.6.20

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

polyfill (side-effect import)

✓ import 'whatwg-fetch'

✗ import { fetch } from 'whatwg-fetch'

The default import is a side-effect that polyfills window.fetch. Named import of fetch is possible but unusual; use in edge cases only.

fetch (named polyfill export)

✓ import { fetch as fetchPolyfill } from 'whatwg-fetch'

✗ import fetch from 'whatwg-fetch'

The named export is the polyfill implementation itself, useful for forcing polyfill when native fetch exists. Default export is not available.

CommonJS require

✓ require('whatwg-fetch')

✗ const { fetch } = require('whatwg-fetch')

The polyfill is side-effect based; require('whatwg-fetch') globally mutates window.fetch. Named destructuring is not supported in CJS.

Shows how to polyfill fetch via import and make a basic JSON request with error handling.

import 'whatwg-fetch'; fetch('/data.json') .then(response => { if (!response.ok) { throw new Error('Network response was not ok'); } return response.json(); }) .then(data => console.log(data)) .catch(error => console.error('Fetch error:', error));

Debug

Known issues

gotchawhatwg-fetch does NOT work in Node.js environments.

fix

Use node-fetch, undici, or built-in global fetch (Node 18+).

affects: *

gotchaHTTP error statuses (4xx, 5xx) do NOT reject the promise; the promise resolves with ok: false.

fix

Always check response.ok or response.status after a fetch.

affects: *

breakingOlder versions (before 3.0) had different export names. Version 3.0+ uses ES modules and modern bundler conventions.

fix

Update to v3 or later and switch to side-effect import 'import "whatwg-fetch"'. For legacy projects, stick with <3.0.

affects: <3.0

gotchaBrowsers with native fetch will NOT use the polyfill; code runs as normal native fetch. This can cause confusion when debugging cross-browser inconsistencies.

fix

Test in older browsers (e.g., IE11) to verify polyfill behavior. For development, consider using browser dev tools to emulate older engines.

affects: *

deprecatedThe package repository has moved from JakeChampion/fetch to github/fetch. Old links may redirect or break.

fix

Use the new repository URL: https://github.com/github/fetch

affects: *

Errors

Common errors & fixes

ReferenceError: fetch is not defined

Using whatwg-fetch in a Node.js environment where fetch is not available.

fix

Do not use this package in Node.js; use 'node-fetch' or the native 'fetch' (Node 18+).

Unhandled promise rejection: TypeError: Failed to fetch

CORS issue: the request was made to a different origin that does not allow CORS.

fix

Ensure the server responds with appropriate CORS headers (Access-Control-Allow-Origin).

SyntaxError: JSON.parse error (or fetch returns undefined)

Missing .json() or .text() call on the response object.

fix

Always call a body method on response: response.json(), response.text(), response.blob(), etc.

Upgrade

Version history

3.6.20latest on npm

Audit

Dependencies

promise-polyfilloptionalRequired for browsers that lack native Promise support (e.g., IE11). Choose any Promises/A+ compatible polyfill.

Agent activity

20 hits · last 30 days

node

Resources

githubhttps://github.com/github/fetch ↗

packagewhatwg-fetch ↗

homepagehttps://github.com/github/fetch#readme ↗