DEV Community: mohammad garmabi

tanstack-fetch 1.6.1: Type-Safe Path Params Without Losing Your DTO Types

mohammad garmabi — Sun, 04 Oct 2026 06:29:20 +0000

tanstack-fetch 1.6.1: Type-Safe Path Params Without Losing Your DTO Types

One of the things I care about when building TypeScript APIs is not just whether the response is typed.

The request itself should be typed too.

Consider this:

await api.get<User>("/users/:id", {
  params: {
    id: userId,
  },
});

At first glance, this looks type-safe.

But there is an important question:

How does TypeScript know that id actually exists in the URL?

And what happens if you accidentally write this?

await api.get<User>("/users/:id", {
  params: {
    userId: 123,
  },
});

The response type is correct.

The request is not.

That is one of the problems I wanted to solve in tanstack-fetch 1.6.1.

What is tanstack-fetch?

tanstack-fetch is a typed Fetch client designed around the mental model of TanStack Query.

It is not an official TanStack package.

The idea is simple:

Keep the native Fetch API model.
Return data directly.
Throw typed FetchErrors for HTTP failures.
Preserve TanStack Query's AbortSignal.
Support SSR and Edge runtimes.
Keep advanced functionality such as SSE and interceptors composable.

The goal is not to replace TanStack Query.

Instead:

TanStack Query manages server state.
tanstack-fetch handles the HTTP transport.

The problem with path parameters

Imagine a typical API:

GET /users/:id

We want the following to be valid:

type User = {
  id: string;
  name: string;
};

type Params = {
  id: number;
};

await api.get<User, Params>("/users/:id", {
  params: {
    id: 123,
  },
});

But these should fail:

await api.get<User, Params>("/users/:id", {
  params: {},
});

Because id is missing.

And:

await api.get<User, Params>("/users/:id", {
  params: {
    userId: 123,
  },
});

Because the URL contains :id, not :userId.

And even this should fail:

await api.get<User, { userId: number }>("/users/:id", {
  params: {
    userId: 123,
  },
});

The type and the URL don't agree.

That's exactly the kind of mistake TypeScript should catch before the request reaches your backend.

What's new in 1.6.1?

Version 1.6.1 introduces typed URL parameters directly from the path.

For example:

type User = {
  id: string;
  name: string;
};

type Params = {
  id: number;
};

await api.get<User, Params>("/users/:id", {
  params: {
    id: 123,
  },
});

Now the relationship between:

/users/:id

and:

{
  id: number
}

is explicit.

If the parameter doesn't exist in the URL, TypeScript rejects it.

Response type + params type

You can keep both the response DTO and parameter map:

await api.get<User, Params>("/users/:id", {
  params: {
    id,
  },
});

The first generic describes the response:

User

The second describes the path parameters:

Params

This gives you two independent layers of type safety:

URL
 ↓
params
 ↓
HTTP request
 ↓
response
 ↓
DTO

What about POST, PUT and PATCH?

The same idea also works for write operations.

For example:

type User = {
  id: string;
  name: string;
};

type Params = {
  id: number;
};

type UpdateUser = {
  name: string;
};

await api.put<User, Params, UpdateUser>("/users/:id", {
  params: {
    id,
  },
  body: {
    name: "Ada",
  },
});

Now we have three different types:

User
  ↓
Response

Params
  ↓
URL parameters

UpdateUser
  ↓
Request body

This makes the contract much more explicit.

Why not just use a route map?

An earlier version of tanstack-fetch experimented with a route map:

createFetch<Routes>()

Version 1.6.1 removes that approach.

Instead, the API keeps the route directly next to the request:

api.get<User, Params>("/users/:id", {
  params: { id },
});

I prefer this approach because the type information stays close to the actual HTTP operation.

There is less global configuration and less ceremony.

A TypeScript limitation behind the API

There is an interesting TypeScript detail here.

TypeScript cannot partially infer generic parameters.

For example:

api.get<User>("/users/:id")

Once User is explicitly supplied, TypeScript can lose the literal information needed to validate the path parameters.

The practical result is that:

api.get<User, Params>("/users/:id", ...)

allows tanstack-fetch to preserve both:

the response DTO
the parameter map

That is why the API intentionally uses multiple type arguments.

What changed from 1.6.0?

The biggest change is actually a simplification.

1.6.0

The API experimented with:

createFetch<Routes>()

and a route map.

1.6.1

That approach is gone.

Instead:

api.get<User, { id: number }>("/users/:id", {
  params: { id },
});

The route itself becomes the source of truth.

This makes the API easier to understand and reduces the amount of global type configuration.

Upgrade

If you're already using tanstack-fetch:

npm install tanstack-fetch@1.6.1

Or:

pnpm add tanstack-fetch@1.6.1

Why this matters

Type safety is often discussed in terms of response objects:

User
Product
Order

But an HTTP request has more than a response.

It has:

Method
URL
Path parameters
Query parameters
Request body
Headers
Response
Errors

If only the response is typed, a significant part of the API contract is still implicit.

With tanstack-fetch 1.6.1, the goal is to make another part of that contract explicit:

/users/:id
       ↓
   { id: number }

Small API details like this can prevent surprisingly common runtime bugs.

Final thoughts

tanstack-fetch started as a small typed wrapper around the Fetch API.

Over time, the focus has shifted toward something more specific:

making HTTP transport predictable, typed, and natural to use with TanStack Query.

Version 1.6.1 is another step in that direction.

Not a huge feature.

Not another abstraction layer.

Just better type safety where it matters.

If you're interested in the implementation and complete API examples:

Documentation: https://mohamadgarmabi.github.io/tanstack-fetch/
1.6.1 release article: https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-1-6
GitHub: https://github.com/mohamadgarmabi/tanstack-fetch
npm: https://www.npmjs.com/package/tanstack-fetch

tanstack-fetch is an independent open-source project and is not an official TanStack package.

tanstack-fetch 1.5.0 — Vue & Nuxt helpers for a TanStack Query–ready fetch client

mohammad garmabi — Thu, 01 Oct 2026 13:41:18 +0000

tanstack-fetch 1.5.0 adds tanstack-fetch/vue: createFetchPlugin, useFetch, and useSse for Vue 3 / Nuxt.

Same client as React — return data, throw FetchError, pass Query's signal.

Not an official TanStack package.

Quick start

import { createFetch } from 'tanstack-fetch'
import { createFetchPlugin, useFetch } from 'tanstack-fetch/vue'

const api = createFetch({ baseUrl: '/api' })
app.use(createFetchPlugin({ client: api }))

// in a component — useFetch injects the client (it does not fetch data)
const api = useFetch()
await api.get('/users')

SSE

import { createFetch } from 'tanstack-fetch/sse'
import { useSse } from 'tanstack-fetch/vue'

const api = createFetch({ plugins: ['sse-resume'] })
const { data, status, close } = useSse('/orders/stream', { client: api })
// status: connecting | connected | disconnected | error

Nuxt name clash

import { useFetch as useFetchClient } from 'tanstack-fetch/vue'

Bundle (gzip)

Entry	Size
HTTP	4.81KB
Vue	0.78KB
SSE	5.94KB

📦 npm · 📘 Vue guide · ⭐ GitHub

tanstack-fetch 1.3 1.4.2: automatic token refresh, built-in DevTools, and a simpler useSse

mohammad garmabi — Wed, 30 Sep 2026 06:43:04 +0000

Refresh tokens without hand-written interceptors, a DevTools panel for HTTP, SSE, SSR and tRPC, and a useSse hook that no longer needs a provider.

tanstack-fetch is a typed fetch client built for TanStack Query. It works with SSR, SSE and tRPC. This post covers what changed from 1.3.0 to 1.4.2. Most of it came from two things I kept hitting in real projects:

Refresh-token logic that everyone writes by hand, and gets subtly wrong.
Not being able to see what a request actually did: how many retries it took, whether the token was refreshed, and which file sent it.

1.3.0: Refresh tokens without the boilerplate

If you've built refresh-token handling on top of fetch or axios, you know the usual problems:

Five requests fail with 401 at the same time, and each one starts its own refresh.
The refresh request itself goes through the auth interceptor and loops.
The token is already expired, but you only find out after a round trip.

createRefreshTokenInterceptor handles all of this:

import { createRefreshTokenInterceptor } from 'tanstack-fetch/plugins'

api.use(
  'refresh-token',
  createRefreshTokenInterceptor({
    refresh: async () => {
      const body = await api.post<{
        accessToken: string
        expiresIn: number
      }>('/auth/refresh', {
        // don't run the refresh request through these interceptors
        interceptors: { eject: ['refresh-token', 'auth'] },
      })
      /* persist body.accessToken + expiresAt */
    },
    before: {
      getExpiresAt: () => expiresAt,
      skewMs: 60_000, // refresh one minute before expiry
    },
    after: { enabled: true },
  }),
)

It works in two ways:

before: refreshes proactively when the token is about to expire, so most requests never see a 401.
after: on the first 401, it refreshes once and retries the original request. The refresh is single-flight: if many requests fail together, they all wait for the same refresh.

The refresh request uses the same api client, so your base URL, headers and plugins still apply. eject just removes the two interceptors that would cause a loop.

1.4.0: DevTools for the whole request lifecycle

This is the biggest change. tanstack-fetch/devtools adds a panel at the bottom of your app that shows every request:

import { createFetch } from 'tanstack-fetch'
import { setupDevtools } from 'tanstack-fetch/devtools'

const api = createFetch({ plugins: ['trace'] })
setupDevtools(api)

That's all. Press Alt+Shift+F (⌥⇧F on macOS) to toggle it.

What you get:

HTTP: status, duration, number of attempts, and the file that made the call (for example profile.hook.ts).
SSE: the list of events for each stream, plus live state. A new onSseClose interceptor hook lets DevTools mark a stream as live and then success when it ends.
SSR: requests made on the server show up too.
tRPC: successful tRPC calls now run onResponse, so DevTools and your own logging see their timing without consuming the response body.
Call graph: click a node, pick Cursor, Zed or VS Code, and the source file opens in your editor. It remembers your choice.

The trace plugin gives each request a stable requestId, so a request and its retries are grouped together.

You can turn each section on or off:

setupDevtools(api, {
  http: true,
  sse: true,
  ssr: true,
  trpc: true,
  open: true, // start expanded
})

If you have several clients, they can share one store:

import { createDevtools, mountDevtools } from 'tanstack-fetch/devtools'

const dt = createDevtools()
const api = createFetch({ plugins: ['trace'], interceptors: [dt.interceptor] })
mountDevtools({ store: dt.store })

1.4.1 and 1.4.2: A simpler `useSse`

Two small changes that make the React hook easier to use.

1.4.1: status instead of isConnected. A boolean couldn't tell "still connecting" apart from "failed". useSse now returns:

type SseStatus = 'connecting' | 'connected' | 'disconnected' | 'error'

onOpen also fires when the stream is actually open, not when subscribing starts.

1.4.2: no FetchProvider required. Pass the client directly:

import { createFetch } from 'tanstack-fetch/sse'
import { useSse } from 'tanstack-fetch/react'

type OrderEvent = { id: string; status: string }

const api = createFetch({
  baseUrl: import.meta.env.VITE_API_URL,
  plugins: ['sse-resume'],
  getToken: () => localStorage.getItem('access_token'),
})

const OrdersLive = () => {
  const { data, status, error, close } = useSse<OrderEvent>('/orders/stream', {
    client: api,
  })

  if (status === 'error') return <p>Stream failed: {error?.message}</p>

  return (
    <div>
      <p>status: {status}</p>
      <p>{data ? `${data.id} · ${data.status}` : 'waiting…'}</p>
      <button type="button" onClick={close} disabled={status === 'disconnected'}>
        Disconnect
      </button>
    </div>
  )
}

Breaking change in 1.4.1: if you used isConnected, replace it with status === 'connected'.

Try it

npm i tanstack-fetch

Docs: https://mohamadgarmabi.github.io/tanstack-fetch/
Live DevTools demo: https://mohamadgarmabi.github.io/tanstack-fetch/examples/devtools
GitHub: https://github.com/mohamadgarmabi/tanstack-fetch

If you try it, I'd love to hear what works and what doesn't: open an issue or leave a comment below. And if it saves you some time, a ⭐ on GitHub helps a lot.

See Every Fetch: DevTools for HTTP, SSE, SSR, and tRPC

mohammad garmabi — Sun, 27 Sep 2026 09:46:13 +0000

tanstack-fetch 1.4.0 introduces tanstack-fetch/devtools: a development-only DevTools dock for inspecting requests directly from the createFetch pipeline.

It tracks:

HTTP
SSR / Edge
SSE
tRPC
request attempts
call sites
SSE events
request timing

And it can jump from a request directly to the source file that triggered it.

The problem

The browser Network tab can tell you:

GET /api/profile
200
143ms

But when debugging an application, you often need:

Who called this?
Was this SSR?
Was the request retried?
Did SSE actually close?
Where did this request originate?
Did tRPC pass through my interceptor?

That's what the new DevTools integration is designed to answer.

Install

npm i tanstack-fetch@1.4.0

import { createFetch } from 'tanstack-fetch'
import { setupDevtools } from 'tanstack-fetch/devtools'

const api = createFetch({
  baseUrl: import.meta.env.VITE_API_URL,
  plugins: ['trace'],
})

if (import.meta.env.DEV) {
  setupDevtools(api)
}

trace is useful because it gives each request a stable ID:

requestId:attempt

That makes retries and repeated requests much easier to distinguish.

Configuration

setupDevtools(api, {
  http: true,
  sse: true,
  ssr: true,
  trpc: true,
  open: false,
})

Shortcut:

Alt + Shift + F

macOS:

⌥ ⇧ F

What does it record?

HTTP

method
path
status
duration
attempts
call site

SSR

The DevTools can distinguish SSR / Edge requests and show incoming authentication context without dumping secrets.

SSE

SSE requests have a stream lifecycle:

pending → live → success

or:

pending → live → error

or:

pending → live → aborted

Each SSE event can also be inspected:

id
name
payload

tRPC

The tRPC adapter marks operations using:

meta.operation = 'trpc'

This lets DevTools group and identify them alongside normal HTTP requests.

Call-site tracking

One of the main reasons I built this is source tracing.

Instead of stopping at:

GET /api/profile

you can inspect the application call graph:

ProfilePage
  ↓
useProfile
  ↓
profile.hook.ts
  ↓
api.get()

Then click the relevant frame and open it in:

Cursor
Zed
VS Code

The editor deep link includes the source location.

Why not just use the Network tab?

Because the Network tab observes the browser's network layer.

This DevTools integration observes the fetch abstraction your application actually uses.

Type	Detection
HTTP	normal fetch calls
SSR	`source: 'ssr' \
SSE	{% raw %}`onSseOpen`, events, `onSseClose`
tRPC	`meta.operation = 'trpc'`

This makes it possible to inspect different application-level request types in one place.

Two lifecycle improvements in 1.4.0

Successful tRPC responses

Previously, successful tRPC responses could skip onResponse.

The adapter now invokes onResponse for successful responses while keeping the response body unread for tRPC parsing.

That makes timing and DevTools instrumentation possible.

SSE close lifecycle

SSE previously had no onSseClose lifecycle hook.

Now:

onSseClose

allows the client and DevTools to distinguish an active stream from a cleanly closed one.

Multiple clients, one DevTools store

If HTTP and SSE use separate factories:

import { createFetch } from 'tanstack-fetch/sse'
import {
  createDevtools,
  mountDevtools,
} from 'tanstack-fetch/devtools'

const dt = createDevtools({
  http: true,
  sse: true,
  ssr: true,
  trpc: true,
})

const api = createFetch({
  plugins: ['trace', 'sse-resume'],
  interceptors: [dt.interceptor],
})

mountDevtools({
  store: dt.store,
  open: true,
})

Both clients can report into the same store and the same dock.

Live demo

You can try it directly in the browser:

DevTools example

No installation required.

Trigger HTTP, upload, SSR, SSE, and tRPC examples, then open the dock with:

Alt + Shift + F

What is tanstack-fetch?

tanstack-fetch is a typed Fetch client designed around the TanStack Query model.

The core contract is intentionally small:

success → data
HTTP error → FetchError
cancellation → AbortSignal

Optional modules add:

SSR
SSE
uploads
React
tRPC
DevTools

It is not an official TanStack package.

Development only

Keep DevTools behind your development environment:

if (import.meta.env.DEV) {
  setupDevtools(api)
}

Links

If you try it in a real application, let me know what you would add next: filters, export, React integration, or something else.

Refresh Tokens Without the Spaghetti: Before Expiry + After 401

mohammad garmabi — Fri, 25 Sep 2026 09:43:58 +0000

How I implemented proactive + reactive token refresh with single-flight in tanstack-fetch 1.3.0

If you've ever implemented access-token refresh, you've probably seen this:

Request A → 401 → refresh
Request B → 401 → refresh
Request C → 401 → refresh
Request D → 401 → refresh

Four requests.

Four refresh calls.

One access token.

This is one of those problems that looks easy until multiple requests fail at the same time.

With tanstack-fetch 1.3.0, I added createRefreshTokenInterceptor to handle both sides of token refresh:

Proactive: refresh shortly before the access token expires.
Reactive: refresh after the first 401.
Single-flight: concurrent requests share the same refresh operation.

Let's look at how it works.

What is tanstack-fetch?

tanstack-fetch is a typed Fetch client designed to work naturally with TanStack Query.

Its core contract is deliberately simple:

HTTP 2xx → return data
HTTP error → throw FetchError
request cancelled → respect AbortSignal

So a query can stay as simple as:

useQuery({
  queryKey: ['users'],
  queryFn: ({ signal }) =>
    api.get('/users', { signal }),
})

There is no .data wrapper and no Axios adapter layer.

The HTTP core is around 3.5 KB gzipped, while SSR, SSE, uploads, React helpers, and tRPC support are available through optional entry points.

tanstack-fetch is an independent package, not an official TanStack project.

The two refresh strategies

There are two common ways to deal with an expiring access token.

1. Refresh before expiry

If we know when the token expires, we can refresh it before sending the request.

For example:

before: {
  getExpiresAt: () => expiresAt,
  skewMs: 60_000,
}

This means:

expiresAt - 60 seconds
          ↓
       refresh
          ↓
     send request

The request gets the new token instead of sending an almost-expired one.

2. Refresh after a 401

Expiration timestamps aren't always perfect.

The server may invalidate a token early, clocks may differ, or the token might have expired between checking it and sending the request.

That's why the interceptor also supports reactive refresh:

Request
   ↓
  401
   ↓
 refresh
   ↓
retry request

The retry happens only for the first unauthorized attempt.

The important part: single-flight refresh

This is where things usually get messy.

Imagine 10 TanStack Query requests are running at the same time.

The token expires.

All 10 requests receive 401.

A naive implementation can produce:

10 requests
    ↓
10 × /auth/refresh

That's unnecessary and can cause even worse problems if the refresh token is rotated.

Instead, createRefreshTokenInterceptor makes refresh single-flight:

Request 1 ─┐
Request 2 ─┤
Request 3 ─┤
Request 4 ─┼──→ refresh()
Request 5 ─┤       │
Request 6 ─┤       ↓
Request 7 ─┤   new access token
Request 8 ─┘       │
                   ↓
              retry requests

Multiple requests can wait for the same refresh operation.

Only one refresh request is made.

The setup

Here's the complete example:

import { createFetch } from 'tanstack-fetch'
import { createRefreshTokenInterceptor } from 'tanstack-fetch/plugins'

let accessToken = localStorage.getItem('access_token')

let expiresAt = Number(
  localStorage.getItem('access_expires_at') ?? 0,
)

const persist = (
  token: string,
  expiresInSeconds: number,
) => {
  accessToken = token

  expiresAt =
    Date.now() + expiresInSeconds * 1000

  localStorage.setItem(
    'access_token',
    accessToken,
  )

  localStorage.setItem(
    'access_expires_at',
    String(expiresAt),
  )
}

export const api = createFetch({
  baseUrl: import.meta.env.VITE_API_URL,

  getToken: () => accessToken,

  onUnauthorized: () => {
    localStorage.removeItem('access_token')
    localStorage.removeItem('access_expires_at')

    window.location.href = '/login'
  },
})

api.use(
  'refresh-token',
  createRefreshTokenInterceptor({
    refresh: async () => {
      const response = await fetch(
        '/auth/refresh',
        {
          method: 'POST',
          credentials: 'include',
        },
      )

      if (!response.ok) {
        throw new Error('refresh failed')
      }

      const body = (await response.json()) as {
        accessToken: string
        expiresIn: number
      }

      persist(
        body.accessToken,
        body.expiresIn,
      )
    },

    // Proactive refresh
    before: {
      getExpiresAt: () => expiresAt,
      skewMs: 60_000,
    },

    // Reactive refresh
    after: {
      enabled: true,
    },
  }),
)

That's basically it.

How the interceptor behaves

The two options have different responsibilities:

Strategy	Trigger	Action
`before`	Token is inside the expiry window	Refresh before request
`after`	First `401`	Refresh and retry
single-flight	Multiple refreshes happen concurrently	Share one refresh operation

This also means you can choose only the behavior you need.

Only reactive refresh

createRefreshTokenInterceptor({
  refresh,

  after: {
    enabled: true,
  },
})

Only proactive refresh

createRefreshTokenInterceptor({
  refresh,

  before: {
    getExpiresAt: () => expiresAt,
    skewMs: 60_000,
  },

  after: false,
})

Both

createRefreshTokenInterceptor({
  refresh,

  before: {
    getExpiresAt: () => expiresAt,
    skewMs: 60_000,
  },

  after: {
    enabled: true,
  },
})

For most applications, having both gives you a useful fallback:

             token nearly expired?
                    │
             ┌──────┴──────┐
             │             │
            yes            no
             │             │
          refresh       send request
             │             │
             └──────┬──────┘
                    ↓
                  API
                    │
                  401?
                    │
             ┌──────┴──────┐
             │             │
             no            yes
             │             │
            done        refresh once
                           │
                           ↓
                         retry

What if refresh fails?

The refresh interceptor doesn't need to own your logout logic.

If refreshing fails, the request can continue through your normal unauthorized handling.

For example:

onUnauthorized: () => {
  localStorage.removeItem('access_token')
  localStorage.removeItem('access_expires_at')

  window.location.href = '/login'
}

This keeps responsibilities separate:

Refresh interceptor

Can this request be recovered with a new token?

Auth layer

Can this user continue their session?

TanStack Query

What should happen to the query state?

I prefer this separation because authentication recovery doesn't end up duplicated across every query or page.

Why not put this inside `useQuery`?

You could do something like this:

useQuery({
  queryKey: ['users'],

  queryFn: async () => {
    try {
      return await api.get('/users')
    } catch (error) {
      // refresh?
      // retry?
      // logout?
    }
  },
})

But then you'll eventually repeat the same logic across multiple queries.

The HTTP layer is a better place for HTTP authentication concerns.

Your query remains:

useQuery({
  queryKey: ['users'],
  queryFn: ({ signal }) =>
    api.get('/users', { signal }),
})

And authentication recovery happens below it.

Other recent improvements

Path-typed parameters — 1.2.1

Path parameters can be inferred directly:

api.get('/users/:id', {
  params: {
    id: userId,
  },
})

Required parameters are inferred from :param and {param} patterns.

First-class 4xx handlers — 1.2.0

The client also includes handlers for common HTTP cases:

onUnauthorized
onTooManyRequests
onClientError
parseRetryAfter

This keeps HTTP error behavior centralized instead of spreading status-code checks throughout your application.

Documentation

I've also been improving the documentation around the project.

It now includes:

a clearer homepage
live comparison examples
StackBlitz examples
llms.txt
a dedicated refresh-token recipe

Install

npm install tanstack-fetch @tanstack/react-query

Then:

import { createFetch } from 'tanstack-fetch'
import { useQuery } from '@tanstack/react-query'

const api = createFetch({
  baseUrl: 'https://api.example.com',
})

useQuery({
  queryKey: ['users'],
  queryFn: ({ signal }) =>
    api.get('/users', { signal }),
})

Links

📦 npm

https://www.npmjs.com/package/tanstack-fetch

📚 Documentation

https://mohamadgarmabi.github.io/tanstack-fetch/

🔐 Refresh Token Recipe

https://mohamadgarmabi.github.io/tanstack-fetch/recipes/refresh-token

💻 GitHub

https://github.com/mohamadgarmabi/tanstack-fetch

📝 Changelog — 1.3.0

https://github.com/mohamadgarmabi/tanstack-fetch/blob/main/CHANGELOG.md

Final thought

Token refresh is easy when you have one request.

It's much more interesting when 10 requests fail simultaneously.

The goal of createRefreshTokenInterceptor is to make that case boring:

Refresh before expiry when possible.
Recover after a 401 when necessary.
Share concurrent refresh operations.
Retry the original request once.
Let the application decide what happens when recovery fails.

If you're using TanStack Query and you've implemented your own refresh queue, I'd be interested in how you handled it.

What edge cases should createRefreshTokenInterceptor handle next?

Issues and PRs are welcome.

tanstack-fetch 1.2.1 — Better DX for TanStack Query & TypeScript Fetch

mohammad garmabi — Sun, 20 Sep 2026 08:31:15 +0000

A few months ago, I introduced tanstack-fetch, a typed HTTP client designed around the mental model of TanStack Query.

Since then, I've been using the feedback from the first release to improve the API, fix issues, and make the developer experience smoother.

Today, tanstack-fetch 1.2.1 is available.

This release is not about adding dozens of new features.

It's about making the existing ones more reliable and easier to use.

What's tanstack-fetch?

If you're using TanStack Query, you probably already have code like this:

useQuery({
  queryKey: ['users'],
  queryFn: async ({ signal }) => {
    const response = await fetch('/api/users', { signal })

    if (!response.ok) {
      throw new Error('Request failed')
    }

    return response.json()
  },
})

The idea behind tanstack-fetch is to move the HTTP concerns into a reusable, typed client:

const api = createFetchClient({
  baseURL: '/api',
})

useQuery({
  queryKey: ['users'],
  queryFn: ({ signal }) =>
    api.get<User[]>('/users', { signal }),
})

The goal is simple:

Let TanStack Query handle server state, while tanstack-fetch handles HTTP.

What's improved in 1.2.1?

The main focus of this release was developer experience and reliability.

Better TypeScript experience

One of the most important goals of the project is to keep the API strongly typed without forcing developers to write a lot of boilerplate.

const user = await api.get<User>('/users/123')

The response type flows directly into your TanStack Query code:

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: ({ signal }) =>
    api.get<User>(`/users/${userId}`, { signal }),
})

The result stays fully typed.

Better error handling

HTTP errors should be useful.

Instead of checking response.ok and manually parsing the response every time, tanstack-fetch provides a structured FetchError.

try {
  await api.get<User>('/users/123')
} catch (error) {
  if (error instanceof FetchError) {
    console.log(error.status)
    console.log(error.message)
    console.log(error.data)
  }
}

This also makes it easier to integrate HTTP errors with TanStack Query's error handling.

useQuery({
  queryKey: ['user'],
  queryFn: ({ signal }) =>
    api.get<User>('/users/123', { signal }),
  retry: (failureCount, error) => {
    if (error instanceof FetchError && error.status === 404) {
      return false
    }

    return failureCount < 3
  },
})

AbortSignal support

Cancellation is especially important when using TanStack Query.

TanStack Query already provides an AbortSignal to the query function:

useQuery({
  queryKey: ['users'],
  queryFn: ({ signal }) =>
    api.get<User[]>('/users', {
      signal,
    }),
})

tanstack-fetch passes that signal through to the underlying Fetch API.

This means requests can be cancelled naturally when queries become obsolete.

Designed for modern TypeScript applications

The project is designed around modern web applications rather than trying to replace every HTTP client.

Current use cases include:

TanStack Query
React
TypeScript
Vite
Next.js
SSR
SSE
file uploads
authentication
request interceptors
retries
OpenAPI-generated clients

The core idea remains the same:

TanStack Query
      ↓
tanstack-fetch
      ↓
Fetch API
      ↓
Your backend

Why not just use Axios?

You absolutely can.

Axios is a mature and widely used HTTP client.

The reason I built tanstack-fetch is different.

Modern applications already have a Fetch API, and TanStack Query already provides the server-state abstraction.

I wanted a small layer between them that focuses on:

TypeScript
Fetch
TanStack Query
consistent errors
cancellation
authentication
SSR
developer experience

Instead of introducing a large abstraction, the goal is to stay close to the platform.

What's next?

Version 1.2.1 is another step toward making the package more stable and useful for real-world applications.

Some of the areas I'm currently interested in improving are:

better documentation
more real-world examples
Next.js App Router examples
TanStack Start examples
better OpenAPI workflows
performance benchmarks
more tests
better developer tooling

I'm also interested in hearing from developers who are actually using it.

If you try tanstack-fetch in a project, I'd love to hear what works well and what doesn't.

Install

npm install tanstack-fetch

or:

pnpm add tanstack-fetch

GitHub:

https://github.com/mohamadgarmabi/tanstack-fetch

NPM:

https://www.npmjs.com/package/tanstack-fetch

Final thoughts

Building a developer tool is a little different from building an application.

The API can look good on day one, but the real test is what happens after people start using it.

That's what I'm focusing on with tanstack-fetch now:

less friction, better types, better DX, and a reliable HTTP layer for TanStack Query.

If you're using TanStack Query and Fetch, give tanstack-fetch a try.

And if you find a bug or have an idea, feel free to open an issue or contribute on GitHub.

Thanks for reading.

tanstack-fetch: A Typed Fetch Client Built for TanStack Query

mohammad garmabi — Sun, 13 Sep 2026 13:35:14 +0000

If you're using TanStack Query with native fetch, your query functions may look like this:

useQuery({
  queryKey: ["users"],
  queryFn: async ({ signal }) => {
    const response = await fetch("/api/users", {
      signal,
    })

    if (!response.ok) {
      throw new Error("Request failed")
    }

    return response.json()
  },
})

There's nothing wrong with this.

But as the application grows, the HTTP layer usually becomes responsible for much more:

Authentication
HTTP error handling
Typed errors
Status-specific behavior
Request cancellation
Retries
Interceptors
SSR
SSE
Logging

This is the problem I wanted to solve with tanstack-fetch.

A small, typed fetch client designed around the mental model of TanStack Query.

It is not an official TanStack package.

Installation

npm install tanstack-fetch @tanstack/react-query

The package requires Node 18+ when running in Node environments because it relies on native Fetch.

1. Create a typed API client

import { createFetch } from "tanstack-fetch"

export const api = createFetch({
  baseUrl: "https://api.example.com",

  getToken: () =>
    localStorage.getItem("access_token"),
})

Now your API client can be used directly inside TanStack Query.

import { useQuery } from "@tanstack/react-query"

type User = {
  id: string
  name: string
}

const usersQuery = useQuery({
  queryKey: ["users"],

  queryFn: ({ signal }) =>
    api.get<User[]>("/users", {
      signal,
    }),
})

Notice that the signal comes directly from TanStack Query.

No custom cancellation mechanism is required.

2. Typed HTTP errors

One important difference between native Fetch and Axios-style clients is HTTP error handling.

fetch() doesn't reject just because the server returns 404 or 500.

For example:

const response = await fetch("/api/users")

can resolve even when:

HTTP 500

was returned.

For a TanStack Query queryFn, that's usually not what we want.

The query function should throw when the HTTP request represents an error.

tanstack-fetch converts HTTP failures into FetchError.

const query = useQuery({
  queryKey: ["users"],

  queryFn: ({ signal }) =>
    api.get<User[]>("/users", {
      signal,
    }),
})

You can inspect the error:

import { isFetchError } from "tanstack-fetch"

if (isFetchError(query.error)) {
  console.log(query.error.status)
  console.log(query.error.code)
  console.log(query.error.body)
}

This makes the transport layer and TanStack Query work together naturally.

3. Global 401 / 403 / 404 / 5xx handling

Instead of repeating authentication logic in every query:

const api = createFetch({
  baseUrl: "https://api.example.com",

  getToken: () =>
    localStorage.getItem("access_token"),

  onUnauthorized: () => {
    localStorage.removeItem("access_token")
    window.location.href = "/login"
  },

  onForbidden: () => {
    console.warn("Forbidden")
  },

  onNotFound: ({ error }) => {
    console.warn("Resource not found:", error.message)
  },

  onServerError: ({ status }) => {
    console.error("Server error:", status)
  },
})

The handler executes before the error is thrown, so TanStack Query still receives the error state.

You can also use an advanced status map:

const api = createFetch({
  baseUrl: "https://api.example.com",

  onStatus: {
    401: () => redirect("/login"),

    403: () => {
      toast.error("Forbidden")
    },

    404: () => {
      toast.error("Not found")
    },

    500: () => {
      toast.error("Server error")
    },

    "5xx": ({ status }) => {
      console.error("Upstream error:", status)
    },

    default: ({ status }) => {
      console.warn("Unhandled:", status)
    },
  },
})

4. Plugins and interceptors

For larger applications, you may need behavior beyond authentication and status handling.

For example:

const api = createFetch({
  baseUrl: "https://api.example.com",

  plugins: [
    "trace",
    "ssr-forward",
    "retry-idempotent",
    "sse-resume",
  ],

  getToken: () =>
    getAccessToken(),
})

You can also create named interceptors:

const api = createFetch({
  baseUrl: "https://api.example.com",

  interceptors: [
    {
      name: "locale",
      order: 25,

      onRequest: (context) => {
        context.request.headers.set(
          "accept-language",
          "en",
        )

        return {
          action: "continue",
          context,
        }
      },
    },
  ],
})

And dynamically register one:

api.use("audit", {
  onResponse: (context) => {
    console.log(
      context.response?.status,
      context.request.url.pathname,
    )

    return {
      action: "continue",
      context,
    }
  },
})

The goal is to keep the HTTP core small while allowing advanced applications to compose additional behavior.

5. React integration

React support is optional.

Install the same package and use:

import {
  FetchProvider,
  useFetch,
} from "tanstack-fetch/react"

Wrap your application:

const App = () => (
  <FetchProvider
    baseUrl={import.meta.env.VITE_API_URL}
    getToken={() =>
      localStorage.getItem("access_token")
    }
  >
    <UsersPage />
  </FetchProvider>
)

Then:

const UsersPage = () => {
  const api = useFetch()

  const { data, error, isPending } = useQuery({
    queryKey: ["users"],

    queryFn: ({ signal }) =>
      api.get<User[]>("/users", {
        signal,
      }),
  })

  if (isPending) {
    return <p>Loading...</p>
  }

  if (isFetchError(error)) {
    return (
      <p>
        {error.status}: {error.message}
      </p>
    )
  }

  return (
    <ul>
      {data.map((user) => (
        <li key={user.id}>
          {user.name}
        </li>
      ))}
    </ul>
  )
}

You don't have to use the React integration.

The core client can be used independently.

6. SSE without forcing it into the core

SSE is available through a separate entry point:

import { createFetch } from "tanstack-fetch/sse"

This is intentional.

The HTTP-only import stays small:

import { createFetch } from "tanstack-fetch"

And streaming functionality is opt-in.

The package currently exposes separate entry points for HTTP, SSE, plugins, and React integration.

7. Why not Axios?

This isn't an attempt to say:

Axios is bad.

Axios is a mature and excellent HTTP client.

The design question was different:

What would a Fetch client look like if its API was designed specifically to fit TanStack Query?

TanStack Query already handles:

Caching
Refetching
Server state
Mutations
Pagination
Infinite queries
Synchronization
Background updates
Cancellation

The HTTP client should focus on HTTP.

That's the separation I wanted.

┌──────────────────────────────┐
│       React / Vue / etc.     │
├──────────────────────────────┤
│        TanStack Query        │
│                              │
│ Cache / Queries / Mutations  │
│ Refetch / Sync / Pagination  │
├──────────────────────────────┤
│        tanstack-fetch        │
│                              │
│ HTTP / Auth / Errors / SSE   │
│ Interceptors / Retries       │
├──────────────────────────────┤
│        Native Fetch         │
└──────────────────────────────┘

TanStack Query itself is transport-agnostic, which is what makes this separation possible.

8. Keep the core small

One of the main design decisions behind the package is opt-in complexity.

The basic case should remain:

const api = createFetch({
  baseUrl: "...",
})

Then:

api.get(...)
api.post(...)
api.put(...)
api.patch(...)
api.delete(...)

If you need SSE:

tanstack-fetch/sse

If you need plugins:

tanstack-fetch/plugins

If you need React integration:

tanstack-fetch/react

This keeps the default API simple and lets bundlers eliminate functionality you don't use. The current package documentation reports the HTTP-only build at roughly 3.5 KB gzip, with separate optional entry points.

9. When should you use it?

I think tanstack-fetch makes the most sense if:

You're already using TanStack Query.
You prefer native Fetch.
You want typed HTTP errors.
You want centralized HTTP status handling.
You need request cancellation.
You want a small transport layer.
You need optional SSE.
You don't want your HTTP client coupled to React.

If you're already happy with Axios or another HTTP abstraction, there's no reason to migrate just because this package exists.

Try it

npm

https://www.npmjs.com/package/tanstack-fetch

GitHub

https://github.com/mohamadgarmabi/tanstack-fetch

I'd love feedback, especially from people working on large TypeScript applications.

The project is still evolving, and I'm particularly interested in what should belong in the core HTTP layer versus what should remain an optional plugin.

Tech stack: TypeScript · Fetch API · TanStack Query · React · SSE · SSR

No monorepo

mohammad garmabi — Thu, 27 Mar 2025 19:15:47 +0000

If you want use to image with auth, install image-auth

mohammad garmabi — Fri, 16 Aug 2024 18:05:30 +0000

🚀 Introducing image-auth - A React Component for Secure Image Handling 🔒

I'm thrilled to announce the release of image-auth, a new React component designed to simplify the process of fetching and displaying images from authenticated endpoints.

Key Features:

Authentication: Securely fetch images with custom headers.
Customizable: Style your images and add fallback options.
Loading & Error Handling: Smooth user experience with placeholders and error fallbacks.
Efficient: Uses native fetch for performance.

Explore more and contribute to the project on npm.
https://lnkd.in/dQDU6kXn

I’m excited to hear your thoughts and see how you use image-auth in your projects! 🚀

React #Image #Auth #npm

please tell me ? SSR or SSG or ISR ? which one of these? #next

mohammad garmabi — Sun, 25 Sep 2022 12:08:58 +0000

DEV Community: mohammad garmabi

tanstack-fetch 1.6.1: Type-Safe Path Params Without Losing Your DTO Types

tanstack-fetch 1.6.1: Type-Safe Path Params Without Losing Your DTO Types

What is tanstack-fetch?

The problem with path parameters

What's new in 1.6.1?

Response type + params type

What about POST, PUT and PATCH?

Why not just use a route map?

A TypeScript limitation behind the API

What changed from 1.6.0?

1.6.0

1.6.1

Upgrade

Why this matters

Final thoughts

tanstack-fetch 1.5.0 — Vue & Nuxt helpers for a TanStack Query–ready fetch client

Quick start

SSE

Nuxt name clash

Bundle (gzip)

tanstack-fetch 1.3 1.4.2: automatic token refresh, built-in DevTools, and a simpler useSse

1.3.0: Refresh tokens without the boilerplate

1.4.0: DevTools for the whole request lifecycle

1.4.1 and 1.4.2: A simpler useSse

Try it

See Every Fetch: DevTools for HTTP, SSE, SSR, and tRPC

The problem

Install

Configuration

What does it record?

HTTP

SSR

SSE

tRPC

Call-site tracking

Why not just use the Network tab?

Two lifecycle improvements in 1.4.0

Successful tRPC responses

SSE close lifecycle

Multiple clients, one DevTools store

Live demo

What is tanstack-fetch?

Development only

Links

Refresh Tokens Without the Spaghetti: Before Expiry + After 401

What is tanstack-fetch?

The two refresh strategies

1. Refresh before expiry

2. Refresh after a 401

The important part: single-flight refresh

The setup

How the interceptor behaves

Only reactive refresh

Only proactive refresh

Both

What if refresh fails?

Why not put this inside useQuery?

Other recent improvements

Path-typed parameters — 1.2.1

First-class 4xx handlers — 1.2.0

Documentation

Install

Links

Final thought

tanstack-fetch 1.2.1 — Better DX for TanStack Query & TypeScript Fetch

What's tanstack-fetch?

What's improved in 1.2.1?

Better TypeScript experience

Better error handling

AbortSignal support

Designed for modern TypeScript applications

Why not just use Axios?

What's next?

Install

Final thoughts

tanstack-fetch: A Typed Fetch Client Built for TanStack Query

Installation

1. Create a typed API client

2. Typed HTTP errors

1.4.1 and 1.4.2: A simpler `useSse`

Why not put this inside `useQuery`?