wretch

library3.0.8jsnpmunverified

A tiny (~1.8KB g-zipped) wrapper around the Fetch API with an intuitive, chainable syntax. v3.0.8 (latest) is actively maintained and supports modern browsers, Node.js 22+, Deno, and Bun. Key differentiators: immutable API (cloning for reuse), automatic JSON serialization/deserialization, error handling via status-specific handlers (notFound, internalError, etc.), addon/middleware system, and full TypeScript types. Compared to alternatives like ky or axios, wretch is lighter and focuses on a minimal, functional style.

devops

npm install wretch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WRETCH

wretch

devopsjavascriptv3.0.8

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.

default export

✓ import wretch from 'wretch'

✗ const wretch = require('wretch')

ESM-only since v3; requires Node with { type: 'module' } or bundler.

WretchError

✓ import { WretchError } from 'wretch'

✗ const { WretchError } = require('wretch')

Named export for error handling; also ESM-only.

Wretch (TypeScript type)

✓ import type { Wretch } from 'wretch'

TypeScript users should import the Wretch type explicitly for type annotations.

WretchAddon / Middleware types

✓ import type { WretchAddon, WretchMiddleware } from 'wretch'

Available as named type exports for custom addons/middlewares.

Basic usage of wretch: create an API client, perform GET/POST requests, handle errors with status-specific callbacks, and retrieve responses as JSON, text, raw Response, or Blob.

import wretch from 'wretch' const api = wretch('https://jsonplaceholder.typicode.com') .options({ mode: 'cors' }) // GET with automatic JSON parsing const post = await api.get('/posts/1').json() console.log(post.title) // POST with automatic serialization const created = await api .post({ title: 'New Post', body: 'Content', userId: 1 }, '/posts') .json() // Error handling with status shortcuts await api .get('/posts/999') .notFound(() => console.log('Post not found!')) .json() // Different response types const text = await api.get('/posts/1').text() const response = await api.get('/posts/1').res() const blob = await api.get('/photos/1').blob()

Debug

Known issues

breakingwretch v3 dropped CommonJS support and is ESM-only.

fix

Use import syntax (import wretch from 'wretch') and ensure your project is ESM (e.g., package.json type: module).

affects: >=3.0.0

breakingDefault export is now a factory function, not a class constructor.

fix

Replace new wretch(...) with wretch(...) (no new keyword).

affects: >=3.0.0

breakingWretchError renamed properties: 'status' was 'statusCode', 'message' was 'text'.

fix

Use error.status and error.message instead of error.statusCode and error.text.

affects: >=3.0.0

gotchaThe .error() handler catches any non-OK response (status >= 400), not just network errors.

fix

Use status-specific handlers (.notFound(), .internalError(), etc.) instead of .error() if you need fine-grained control.

affects: *

deprecatedwretch().body() is deprecated in v3. Use wretch().content() instead.

fix

Replace .body() with .content() for setting request body content types.

affects: >=3.0.0

gotchawretch v3 requires Node.js >=22; older Node versions will fail.

fix

Upgrade Node.js to 22+ or use wretch v2 (but v2 is in maintenance mode).

affects: >=3.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/wretch/dist/index.js from /path/to/your/file.js not supported.

wretch v3 is ESM-only, but you're using require() in a CommonJS context.

fix

Switch your project to ESM (add "type": "module" to package.json) or use dynamic import() instead of require().

TypeError: wretch is not a constructor

Using new wretch() which is invalid in v3 (wretch is a factory function).

fix

Remove the new keyword: const api = wretch('https://example.com').

TypeError: wretch(...).body is not a function

.body() was removed in v3; use .content() instead.

fix

Replace .body(contentType) with .content(contentType).

Property 'statusCode' does not exist on type 'WretchError'.

WretchError property renamed in v3 from statusCode to status.

fix

Use error.status instead of error.statusCode.

Upgrade

Version history

3.0.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Resources

githubhttps://github.com/elbywan/wretch ↗

packagewretch ↗

homepagehttps://elbywan.github.io/wretch ↗