Package Exports

itty-fetcher

Readme

Documentation | Discord

itty-fetcher is a lightweight wrapper around the native fetch API that eliminates the common boilerplate when making API calls.

✨ Key Features

Automatic - JSON parsing, payload serialization, HTTP error throwing, etc.
Composable - Set up your API/endpoint once, then call it cleanly
Human-Readable - Method calls that feel natural
- fetcher().get('/users')
- users.post({ name: 'Steve', age: 24 })
100% TypeScript - Intelligent type inference with generics for request/response shapes
Universal - Works everywhere fetch is supported... or not (through polyfills)

...and of course itty, at under 650 bytes. We got you, fam.

Allows this:

const newUser = await fetcher().post('/api/users', { name: 'Alice' })

Instead of this:

const newUser = await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Alice' })
}).then(response => {
  if (!response.ok) throw new Error(`${response.status}: ${response.statusText}`)

  return response.json()
})

Quick Start

Option 1: Import

import { fetcher } from 'itty-fetcher'

Option 2: Just copy this snippet:

let fetcher=(e,s)=>{let t="string"==typeof e?{base:e,...s}:e||{};return new Proxy((()=>{}),{get:(e,s)=>(...e)=>(async(e,s,t,r=("string"==typeof t[0]?t.shift():""),a=("GET"!=e?t.shift():null),n={...s,...t.shift(),method:e},o=new Headers(s.headers),i="string"==typeof a,f=s.base??"")=>{r=new URL((r.includes("://")?r:(f.includes?.("://")?f:globalThis.location?.href+"/"+f)+(r?"/"+r:"")).replace(/\/+/g,"/"));for(let e in n.query||{})r.searchParams.append(e,n.query[e]);n.body=a,a&&0!=n.encode&&(n.body=i?a:JSON.stringify(a),!i&&o.set("content-type","application/json"));for(let[e,s]of new Headers(n.headers||[]))o.set(e,s);let p=await(n.fetch||fetch)(new Request(r,{...n,headers:o})),c=p.ok?void 0:Object.assign(new Error(p.statusText),{status:p.status,response:p});if(n.parse??"json")try{p=await p[n.parse??"json"](),c&&"json"==(n.parse??"json")&&(c={...c,...p})}catch(e){!c&&(c=Object.assign(new Error(e.message),{status:p.status,response:p}))}for(let e of n.after||[])p=await e(p)??p;if(n.array)return[c,c?void 0:p];if(c)throw c;return p})(s.toUpperCase(),t,e)})};

Note: This will lose TypeScript support, but is great for adding to your browser console (via script extensions, etc).

Basic Usage

import { fetcher } from 'itty-fetcher'

// simple one line fetch
fetcher().get('https://example.com/api/items').then(console.log)

// ========================================================

// or make reusable api endpoints
const api = fetcher('https://example.com', {
  headers: { 'x-api-key': 'my-secret-key' },
  after: [console.log],
})

// to make api calls even sexier
const items = await api.get('/items')

// no need to encode/decode for JSON payloads
api.post('/items', { foo: 'bar' })

Philosophy

Like any itty.dev project, this is not a kitchen-sink library. If you need advanced features like automatic retries or complex request interception, consider a more full-featured library. This is for when you want native fetch behavior with dramatically less boilerplate.

✅ Perfect for:

Removing boilerplate from fetch calls
Projects using native fetch today
Composable API clients
Simple use-cases where size matters

❌ Consider alternatives for:

Automatic retries or timeout handling
GraphQL (use a GraphQL client)
Complex request/response middleware
Very advanced edge-cases

Next Steps

Getting Started - Basic setup and first API calls
Configuration - All available options
API Reference - Complete method documentation
TypeScript Guide - Type-safe usage patterns
Examples - Real-world usage examples

Built with ❤️ by Kevin Whitley and the Itty community.