cross-fetch
A universal WHATWG Fetch API implementation that works across Node.js, browsers, and React Native.
What is cross-fetch?
cross-fetch is a universal implementation of the WHATWG Fetch API that works consistently across Node.js, browsers, React Native, and worker environments. It solves the problem of writing platform-specific HTTP request code by providing a single, standardized interface that behaves identically wherever JavaScript runs.
JavaScript developers building applications that need to run across multiple environments (Node.js, browsers, React Native, workers) and want consistent HTTP request handling without platform-specific code.
Developers choose cross-fetch because it provides a simple, zero-configuration way to use the standard Fetch API everywhere, with the flexibility to use it as either a polyfill or ponyfill based on their risk tolerance and architectural preferences.
Overview
Universal WHATWG Fetch API for Node, Browsers and React Native.
Use Cases
Best For
- Building isomorphic JavaScript applications that run on both server and client
- Creating React Native apps that need consistent networking with web counterparts
- Developing libraries or SDKs that must work across multiple JavaScript environments
- Writing universal code for Service Workers or CloudFlare Workers
- Migrating codebases between Node.js and browser environments without rewriting HTTP logic
- Projects requiring fetch API consistency without global namespace pollution (using ponyfill mode)
Not Ideal For
- Projects running exclusively on Node.js 18+ or modern browsers where fetch is natively supported and no cross-platform consistency is needed
- Applications requiring advanced HTTP client features like automatic retries, interceptors, or request cancellation out of the box
- Teams that prioritize minimal bundle size and can use environment-specific fetch implementations without abstraction
- Environments where strict control over underlying network libraries is critical, as cross-fetch proxies to third-party libs like node-fetch
Pros & Cons
Pros
Works identically on Node.js, browsers, React Native, and workers by proxying to environment-specific implementations like node-fetch and whatwg-fetch, as stated in the README's 'How does cross-fetch work?' section.
Offers flexibility to use as a polyfill (global) or ponyfill (local import), allowing developers to avoid global namespace pollution if desired, highlighted in the install and usage examples.
No setup or instantiation required—just import and use the fetch function directly, making it easy to integrate, as demonstrated in the usage code snippets.
Adheres to the WHATWG Fetch API specification, ensuring consistent behavior across all supported environments, which is a core philosophy mentioned in the README.
Cons
Relies on underlying libraries like node-fetch and whatwg-fetch, so bugs or breaking changes in those dependencies can affect cross-fetch without direct control, as noted in the proxy mechanism explanation.
Only provides basic fetch functionality; lacks built-in support for common needs like request timeouts, progress tracking, or automatic retries, requiring additional code or libraries for complex use cases.
Using polyfill mode introduces risk if the Fetch spec evolves, potentially causing debugging issues, and adds unnecessary bundle size in environments where fetch is already native, as warned in the FAQ.
Frequently Asked Questions
Related Projects
resize-observer-polyfillA polyfill for the Resize Observer API
css-vars-ponyfillClient-side support for CSS custom properties (aka "CSS variables") in legacy and modern browsers
rafrequestAnimationFrame polyfill library
abortcontroller-polyfillPolyfill for the AbortController DOM API and abortable fetch (stub that calls catch, doesn't actually abort request).
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.