TopGit
GitHub Repo Review

whatwg-fetch polyfill: window.fetch for old browsers

WTopGit review image for JakeChampion/fetch
Review by Topgit.dev for JakeChampion/fetch, with GitHub repository stats and README context.
Quick verdict

whatwg-fetch patches window.fetch so promise-based HTTP requests work in browsers that never shipped native Fetch support. It's the right call while Internet Explorer 10 or 11 is still in your browser matrix, and dead weight the moment it isn't — modern Chrome, Firefox, and Safari already implement fetch natively, so the polyfill code just sits unused in the bundle.

Stars
★ 25.8k
Forks
⑂ 2.8k
Language
JavaScript
License
MIT
Topic
Frontend
Updated
Jul 2024
Homepage
—
GitHub

What is whatwg-fetch?

whatwg-fetch is a JavaScript polyfill, published as the npm package whatwg-fetch, that implements a subset of the WHATWG Fetch specification, enough to replace most XMLHttpRequest use in browsers without native fetch. Importing it patches the global window.fetch directly, so code that already calls fetch() just starts working. It's browser-only — the README says it doesn't work under Node.js.

Supported fetch features and options

  • ✓Implements a subset of the WHATWG Fetch spec — enough to cover typical XMLHttpRequest replacement cases, not the full spec surface.
  • ✓Promise-based fetch() calls that resolve with a Response object exposing .status, .statusText, .headers.get(), .json(), and .text().
  • ✓Built-in FormData support for posting forms and uploading files without constructing a raw XHR request.
  • ✓Supports the abortable fetch pattern via AbortController and AbortSignal, once paired with an AbortController polyfill on browsers that lack one.
  • ✓Configurable credentials option (same-origin by default, include for CORS requests) for controlling cookie behavior across origins.
  • ✓Exports the polyfill implementation directly (import {fetch as fetchPolyfill} from 'whatwg-fetch') so you can call it explicitly alongside a native window.fetch.
How this repository's GitHub stars have grown over time. Source: star-history.com.View the star history ↗

Installing whatwg-fetch

Install it with `npm install whatwg-fetch --save`. The README also flags a second dependency worth not skipping: whatwg-fetch needs a Promise polyfill on older browsers, and the project points to taylorhakes/promise-polyfill for that. For webpack builds, add 'whatwg-fetch' to the entry array ahead of your application's entry point so the global patch runs before your code does.

Using the polyfill in your code

Importing whatwg-fetch runs the polyfill immediately and patches window.fetch: `import 'whatwg-fetch'` then call `window.fetch(...)` as usual. If you need the polyfill implementation specifically — for example to get abort support in a browser with an outdated native fetch — import it by name instead: `import {fetch as fetchPolyfill} from 'whatwg-fetch'`. From there the calling patterns match the spec: `fetch('/users.json').then(r => r.json())` for JSON, passing a FormData instance as body for file uploads, and reading `response.headers.get('Content-Type')` or `response.status` off the resolved Response.

Strengths

  • ✓Drop-in for the real fetch() call shape — code written against the polyfill needs no changes when native fetch takes over in modern browsers.
  • ✓Small, single-purpose scope: it patches one global and gets out of the way instead of bundling a full HTTP client with interceptors and config layers.
  • ✓The README's caveats section is unusually direct about what doesn't work (keepalive, redirect modes, cache directives), so you're not left discovering the gaps by trial and error.
  • ✓MIT-licensed and small enough to read the whole implementation in one sitting if a request behaves unexpectedly.

Known limitations and caveats

  • △The returned Promise does not reject on HTTP error status — a 404 or 500 response resolves normally, so you need your own status check (the README's checkStatus() pattern) to treat error codes as failures.
  • △keepalive isn't supported at all, because implementing it would require a synchronous XHR call, which the maintainers have explicitly declined to add.
  • △redirect and cache request options are ignored — only the default 'follow' redirect behavior works, since XMLHttpRequest under the hood doesn't expose the other modes.
  • △Cookie defaults vary by browser version: Firefox 39-60, Chrome 42-67, and Safari 10.1-11.1.2 defaulted to 'omit' under an older fetch spec draft, so targeting those versions means setting credentials explicitly rather than relying on the default.
  • △Aborting requests needs a second polyfill (AbortController/AbortSignal aren't included), and response.url can be unreliable after redirects on older browsers unless the server sets an X-Request-URL header.

Alternatives to whatwg-fetch

unfetch — a much smaller fetch polyfill for teams that only need the minimal Promise + fetch surface and don't care about full spec coverage.axios — a full HTTP client with interceptors, automatic JSON parsing, and request/response transforms, at the cost of a much bigger dependency than a polyfill.cross-fetch — a fetch implementation aimed at isomorphic code that needs the same fetch() call to work in both the browser and Node.js, which whatwg-fetch explicitly does not support.

Frequently asked questions

Does whatwg-fetch work in Internet Explorer 10 and 11?

whatwg-fetch is built to work in Internet Explorer 10 and 11, listed explicitly in the README's browser support section alongside Chrome, Firefox, and Safari 6.1+. Since IE never implemented window.fetch natively, this is one of the main reasons the polyfill exists — without it, fetch() simply isn't a function you can call in those browsers.

How do I make fetch reject on HTTP error status with whatwg-fetch?

whatwg-fetch's returned Promise resolves normally even on a 404 or 500 response — it only rejects on network failure. To make errors reject, write a status-checking function that throws when response.status falls outside the 200-299 range, then chain it before your .then(parseJSON) call, exactly as the README's checkStatus() example shows.

Why are cookies not sent by default in whatwg-fetch?

whatwg-fetch defaults the credentials option to 'same-origin', so cookies go to the same domain automatically but not to other domains during CORS requests. For cross-origin requests that need cookies, set credentials: 'include' explicitly — older Firefox, Chrome, and Safari versions defaulted to 'omit' under an earlier fetch spec draft, so explicit credentials avoid surprises.

Can I use whatwg-fetch with webpack?

whatwg-fetch works with webpack: add the package name to the entry array before your application's own entry point in the webpack config, so the global window.fetch patch runs before your app code needs it. This is the exact pattern the README documents for bundler setups, with no extra loader or plugin required.

Does whatwg-fetch support aborting requests with AbortController?

whatwg-fetch supports the abortable fetch pattern, but only when paired with a separate AbortController/AbortSignal polyfill, since browsers old enough to lack native fetch also lack those DOM APIs.

What happens when whatwg-fetch runs in a modern browser?

whatwg-fetch has no effect in modern browsers that already implement window.fetch natively — the README states plainly that none of the polyfill's code executes there. Importing it is harmless but redundant: fetch() calls just use the browser's built-in implementation, which is also why bug reports about native fetch behavior belong with the browser vendor, not this project.

The problem it solves

Before native fetch existed, writing cross-browser HTTP requests meant hand-coding XMLHttpRequest's callback-based, non-Promise API — different handling for building forms, reading headers, and catching errors depending on which browser you targeted. whatwg-fetch's specific fix is narrower than 'make HTTP easier': it lets you write against the real, Promise-based fetch() signature everywhere, including Internet Explorer 10 and 11, so a codebase doesn't need one request pattern for old browsers and another for modern ones.

Best use cases

  • •Shipping a production web app that still has to support Internet Explorer 10 or 11 without maintaining two separate request code paths.
  • •Standardizing a codebase on the fetch() API before dropping IE support, so removing the polyfill later is a one-line change.
  • •Using webpack and wanting fetch available globally by adding whatwg-fetch to the entry array ahead of the application entry point.
  • •Handling FormData-based file uploads in older browsers where writing raw XMLHttpRequest boilerplate would take more code.

Who should try it — and who should skip

Teams shipping to Internet Explorer 10 or 11 — or any environment without native fetch — should add whatwg-fetch and write against the real fetch() API instead of hand-rolling XMLHttpRequest wrappers. Teams that have already dropped IE and only target evergreen Chrome, Firefox, and Safari should skip it: the README itself says the polyfill code has no effect there, so it's pure bytes with no behavior change. Anyone needing request/response interceptors, automatic retries, or Node.js compatibility should look at a fuller HTTP client instead of a fetch shim.

Related repositories

Source & attribution

Based on the JakeChampion/fetch GitHub repository (https://github.com/JakeChampion/fetch), including its README and published repo metadata.

GitHub data · last synced Aug 15, 2026Reviewed by Henry
← Back to TopGit

Want a second opinion on fetch?

Ask an AI that can read this page — one click and you get its take on fetch.

GitHub