A Tiny Fetch Wrapper That Makes HTTP Requests Feel Less Tedious

If you've ever written a fetch call and then spent the next twenty lines manually checking status codes, setting headers, and calling .json() on the response, you know the drill. The native Fetch API works fine, but it leaves a lot of boilerplate for you to handle yourself. Wretch is a small wrapper around fetch that tries to make that whole process feel more natural.

What It Does

Wretch is a wrapper built around the Fetch API with an intuitive, chainable syntax. The core is less than 1.8KB g-zipped, and it's written in TypeScript, so you get strong typing out of the box. It's designed to simplify how you perform network requests and handle responses, taking care of things like errors, headers, and serialization for you.

The library is isomorphic, meaning it works in modern browsers, Node.js 22+, Deno, and Bun. Every call creates a cloned instance, so instances are immutable and can be reused safely across your codebase. It's also modular: you can plug in addons to add new features and middlewares to intercept requests. The project is fully covered by unit tests and has been maintained for years.

Why It's Cool

• The syntax reads like a sentence. You create a client, chain the options you want, and then make your request. api.get("/posts/1").json() is about as clean as it gets. There's no ceremony, no manual response parsing, no forgetting to check response.ok.

• Error handling is built into the chain. Instead of wrapping everything in try/catch blocks and inspecting status codes, you can attach handlers directly. The README shows .notFound(() => console.log("Post not found!")) right in the middle of a request chain. That's a genuinely nicer way to think about HTTP errors.

• Automatic serialization and deserialization. When you POST an object, wretch serializes it for you. When you want JSON back, you call .json() and get a parsed object. You don't have to think about JSON.stringify or response.json() unless you want to.

• Multiple response types without extra work. Need raw text? Call .text(). Need the raw Response object? Call .res(). Need binary data? Call .blob(). Each of these is a single method call, which keeps your request code consistent regardless of what you're fetching.

• Immutability means safety. Because every call returns a cloned instance, you can build up a base client with shared configuration (like CORS mode or base URL) and reuse it everywhere without worrying about one request mutating state for another.

• It's small. At under 1.8KB g-zipped, the core doesn't add meaningful weight to your bundle. That matters if you're shipping to the browser and you care about performance budgets.

• Modularity without complexity. Addons and middlewares let you extend the library when you need to, but you're not forced to think about them for basic usage. The core stays lean, and you opt into extra features only when they're relevant.

How to Try It

Getting started is about as simple as it gets.

1. Install it:

npm i wretch

1. Import it and create a reusable API client:

import wretch from "wretch"

const api = wretch("https://jsonplaceholder.typicode.com")
  .options({ mode: "cors" })

1. Make requests with automatic JSON handling:

const post = await api.get("/posts/1").json()
console.log(post.title)

1. POST with automatic serialization:

const created = await api
  .post({ title: "New Post", body: "Content", userId: 1 }, "/posts")
  .json()

1. Handle errors elegantly:

await api
  .get("/posts/999")
  .notFound(() => console.log("Post not found!"))
  .json()

1. Use different response types as needed:

const text = await api.get("/posts/1").text()      // Raw text
const response = await api.get("/posts/1").res()   // Raw Response object
const blob = await api.get("/photos/1").blob()     // Binary data

You can find the full documentation, including the API reference, recipes, addons, and middlewares, at the repository on GitHub. Note that Wretch 3.0 is now live, so if you're upgrading from v2, there's a migration guide available.

Final Thoughts

Wretch isn't trying to reinvent HTTP. It's trying to make the common case of "make a request, get a response, handle errors" less annoying, and it does that well. If you're building something that talks to an API and you're tired of writing the same fetch boilerplate over and over, this is worth a look. It's small, typed, and maintained, which is about all you can ask for from a utility library. The fact that it works across Node, Deno, Bun, and browsers means you can use it in pretty much any modern JavaScript project without thinking twice.

Follow @githubprojects for more developer tools and open source projects.