wretch
A tiny wrapper built around fetch with an intuitive syntax for making HTTP requests.
What is wretch?
Wretch is a tiny JavaScript library that wraps the native Fetch API with a more intuitive and chainable syntax. It simplifies making HTTP requests by automatically handling JSON serialization, error catching, and request configuration, reducing the boilerplate code typically required with fetch. It solves the problem of verbose and repetitive network request code in modern web applications.
Frontend and full-stack JavaScript/TypeScript developers who frequently make HTTP requests and want a cleaner, more maintainable alternative to raw fetch or heavier HTTP clients.
Developers choose Wretch for its minimal footprint (~1.8KB gzipped), elegant API that reduces fetch boilerplate, and extensible design through addons and middlewares. It offers better error handling, immutability for safe reuse, and full TypeScript support out of the box.
Overview
A tiny wrapper built around fetch with an intuitive syntax. :candy:
Use Cases
Best For
- Building REST API clients with reusable configuration and error handling
- Simplifying fetch usage in TypeScript projects with full type safety
- Adding middleware like retry logic or request deduplication to HTTP calls
- Handling file uploads with progress tracking via addons
- Creating isomorphic HTTP clients that work in browsers, Node.js, Deno, and Bun
- Reducing boilerplate code for JSON request/response cycles in frontend apps
Not Ideal For
- Cloudflare Workers projects, due to a known incompatibility with the Response type property that requires a custom middleware workaround.
- Legacy JavaScript environments (Node.js <22 or older browsers), as Wretch relies on modern fetch implementations and may not work out-of-the-box without polyfills.
- Teams needing built-in GraphQL or WebSocket support, since Wretch is focused on RESTful HTTP requests and requires additional setup for other protocols.
- Applications where strict control over header case sensitivity is critical, because of the fetch API's behavior that Wretch doesn't fully abstract.
Pros & Cons
Pros
Provides a cleaner syntax than raw fetch, with methods like .json() and .post() that automatically handle serialization and headers, reducing boilerplate code as shown in the README examples.
Includes catchers for common HTTP status codes (e.g., .notFound(), .unauthorized()), eliminating the need for manual error checking and throwing, which simplifies response handling.
Supports addons (e.g., for progress tracking, form data) and middlewares (e.g., retry, dedupe) that can be plugged in to extend functionality without bloating the core library.
Works seamlessly in modern browsers, Node.js 22+, Deno, and Bun, making it suitable for isomorphic applications as highlighted in the compatibility section.
Written in TypeScript, offering strong typing for requests and responses, which enhances developer experience and code safety, with examples provided in the README.
Cons
Does not work out-of-the-box in Cloudflare Workers due to a missing Response.type property, requiring a custom middleware workaround as documented in the limitations section.
Inherits fetch's case-insensitive headers, which can lead to duplicate header values if set with different cases, and Wretch doesn't automatically deduplicate them, potentially causing issues.
Major version upgrades (e.g., v2 to v3) introduce breaking changes, necessitating code migrations as indicated by the provided migration guides, which can be disruptive for teams.
Advanced functionalities like retry logic or caching require importing separate middlewares, adding complexity and dependencies for teams needing those features out-of-the-box.
Frequently Asked Questions
Related Projects
axiosPromise based HTTP client for the browser and node.js
React Query🤖 Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.
swrReact Hooks for Data Fetching
unfetch🐕 Bare minimum 500b fetch polyfill.
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.