Wretch

Qué es

Wretch es una librería ligera (alrededor de 1,8 KB gzip) escrita en TypeScript que envuelve la API Fetch del navegador con una sintaxis fluida y encadenable. La creó Julien Elbaz (elbywan) y se distribuye con licencia MIT. Funciona en navegadores modernos, Node.js 22+, Deno y Bun, y aporta tipado completo de TypeScript.

Para qué sirve

• Construir peticiones HTTP encadenando URL, cabeceras, cuerpo y método de forma legible.
• Serializar y deserializar JSON automáticamente sin tener que llamar a response.json().
• Manejar errores con catchers específicos por código de estado (401, 404, 500…).
• Reutilizar instancias inmutables como cliente base para una API y derivar variantes.

Cuándo usarlo

Es buena opción cuando trabajas directamente sobre fetch y quieres una capa más cómoda sin renunciar a su ligereza, especialmente en proyectos que valoran un bundle pequeño. Si necesitas interceptores avanzados, cancelación y un ecosistema más grande, axios o ky son alternativas a considerar; Wretch destaca por su tamaño mínimo y su API encadenable.

Ejemplo

Instalación y uso básico:

npm install wretch

import wretch from "wretch"

const api = wretch("https://api.example.com")
  .headers({ "X-Api-Key": "secret" })

// POST con cuerpo JSON y manejo de errores por estado
const user = await api
  .url("/users")
  .json({ name: "Alice" })
  .post()
  .unauthorized(() => console.log("Sin autorización"))
  .json()

console.log(user)

Puntos clave

• API fluida que separa la cadena de petición (URL, cabeceras, cuerpo, método) de la de respuesta (catchers y tipos de respuesta).
• Catchers por código de estado para tratar errores HTTP de forma declarativa.
• Instancias inmutables y reutilizables, seguras para usar como cliente base compartido.
• Sistema modular de addons y middlewares para ampliar su comportamiento.

Ten en cuenta

Requiere un entorno con la API Fetch disponible (en Node.js, versión 22 o superior). La versión 3.0 introdujo cambios respecto a la 2.x, así que conviene revisar la guía de migración al actualizar. Para necesidades muy complejas de cliente HTTP, otras librerías ofrecen más características de serie a cambio de un mayor tamaño.