DEV Community: Mohammad Garmabi

tanstack-fetch 2.2.1: I audited every entry point and fixed 31 bugs

Mohammad Garmabi — Sat, 14 Nov 2026 11:08:04 +0000

tanstack-fetch 2.2.1 adds no new features. I went through every entry point (core, /sse, /trpc, the framework adapters, DevTools, and the CLI) and fixed 31 bugs. Each fix has a regression test.

npm install tanstack-fetch@2.2.1

If you haven't seen it before: tanstack-fetch is a small, typed fetch client built for TanStack Query. It has guides for React, Vue, Next.js, Nuxt, Solid, Svelte/SvelteKit, Angular and TanStack Start.

Here are the fixes most likely to have affected you.

1. A relative `baseUrl` actually works now

const api = createFetch({ baseUrl: '/api' })
await api.get('/users')
// 2.2.0 → TypeError: Invalid URL
// 2.2.1 → GET https://your.site/api/users

In the browser it resolves against location.href. On the server you get a clear error asking for an absolute baseUrl, so it no longer fails with a vague message.

2. Retries no longer re-send your POST by accident

Three fixes:

Interceptor errors thrown in onResponse / onResponseError, such as an onUnauthorized redirect, were wrapped as NETWORK_ERROR and could be retried, which meant re-sending a POST. They now propagate unchanged and are never retried.
controller.abort(reason) was treated as a network error and retried. It now rejects with your reason, with no retry.
{ action: 'drop' } in onRequest was typed but ignored. It now rejects with REQUEST_DROPPED, and fetch is never called.

3. SSE resume does what its name says

Before this release, only a bad status at connect time went through the reconnect path. A mid-stream drop went straight to your code, and Last-Event-ID was never sent.

const api = createFetch({ baseUrl, plugins: ['sse-resume'] })

for await (const event of api.sse<Order>('/orders/stream')) {
  // after a drop: reconnects after 1s with Last-Event-ID: 7, continues at event 8
}

Other SSE fixes:

api.sse('/chat', { body: { prompt } }) now sends a POST with the body. Before, it sent a GET and dropped the body.
The parser now handles \r\n split across chunks, id:-only blocks and bare data lines.
onSseClose runs exactly once, and close() during the reconnect wait actually stops the reconnect.

4. SSR leaks in Vue/Nuxt and Svelte

Vue/Nuxt useSse / useWs were opening connections during SSR. They now connect only in the browser.
Svelte's setFetchClient() stored the client in a module-level variable, shared across SSR requests. On the server, the client now comes from Svelte context only.

5. A DevTools XSS

The DevTools panel used innerHTML to render values that partly came from a response header (x-tanstack-fetch-mock), so a server could inject script into it. Every element is now built with textContent.

6. Codemods that produce working code

migrate converts ky's ky.get(url).json<User>() to api.get<User>(url).
It renames axios params: to query: only at the top level of the config, not inside request bodies.
It puts the new import after 'use client'.
generate (OpenAPI) now outputs valid TypeScript: it quotes keys like 'content-type' and de-duplicates colliding names.

Behaviour changes to check

Interceptor errors are rethrown as-is, with no retry.
abort(reason) rejects with reason.
An SSE call with a body sends a POST.
sse-resume reconnects after drops and 5xx responses.
A WebSocket's reconnect counter resets only after 5s of stable connection.
A relative tRPC URL on the server now throws.

Cost

The core grew by about 260 bytes gzip (3.71KB → 3.97KB).

Known limits

Solid, Svelte and Angular useSse / useWs still don't re-subscribe when path or options change. That's planned for the next minor release.

📖 Full release notes · ⭐ GitHub · 📦 npm · 📚 Docs

If you use it, I'd love to hear which of these bugs you'd already run into. Issues and stars are very welcome.

Mock Your API Inside the Client: HTTP, SSE, NDJSON & WebSocket with tanstack-fetch

Mohammad Garmabi — Mon, 09 Nov 2026 07:15:08 +0000

Build the whole frontend while the backend is still two weeks out — then swap in the real API one endpoint at a time, without touching a single component.

Originally published on the tanstack-fetch blog.

The design is approved, the sprint has started, and the backend is two weeks behind. Your usual options all have a cost:

Hard-coded data in components skips the loading, error and retry paths — exactly the parts that break later.
A separate mock server is one more process to run, and most stop at REST. A live price feed over SSE or a chat over WebSocket? You're on your own.
Service-worker mocks need extra setup per environment, and streaming support varies.

tanstack-fetch takes a different route: a mocks option that answers requests inside the client. The mock code lives in its own entry, tanstack-fetch/mock (1.82 KB gzip), so apps that don't use it pay nothing. It covers every transport the client speaks — HTTP, SSE, NDJSON streams, WebSocket, upload and tRPC. Your interceptors keep running, and every route has its own on/off switch.

In this tutorial we'll build the data layer of a small trading dashboard:

A REST endpoint — market overview
A live SSE feed — price ticks
A streaming NDJSON endpoint — an AI market summary
A WebSocket room — trader chat
Errors and latency
Switching to the real API, one route at a time

Stack: tanstack-fetch/live · any framework · optional @tanstack/react-query

npm install tanstack-fetch

Step 1 — One client, one switch

Put the mocks next to the client you already have:

// src/lib/api.ts
import { createFetch } from 'tanstack-fetch/live'
import { createMocks } from 'tanstack-fetch/mock'
import { routes } from '../mocks'

export const api = createFetch({
  baseUrl: import.meta.env.VITE_API_URL,
  getToken: () => localStorage.getItem('token'),
  mocks: createMocks({
    enabled: import.meta.env.VITE_USE_API_MOCK !== 'false',
    delayMs: 250, // feel the loading states
    routes,
  }),
})

VITE_USE_API_MOCK=false turns every mock off. Requests that no route matches always go to the real API, so you only mock what's missing.

Step 2 — A REST endpoint

// src/mocks/market.ts
import type { MockRequest } from 'tanstack-fetch/mock'

export const getMarketOverviewMock = ({ query }: MockRequest) => ({
  currency: query.get('currency') ?? 'USD',
  markets: [
    { symbol: 'BTC', price: 67_250, change: 1.8 },
    { symbol: 'ETH', price: 3_410, change: -0.4 },
  ],
})

// src/mocks/index.ts
import type { MockRoute } from 'tanstack-fetch/mock'
import { getMarketOverviewMock } from './market'

export const routes: MockRoute[] = [
  { method: 'GET', path: '/market/overview', handler: getMarketOverviewMock },
]

Your component code is exactly what ships to production:

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

The handler receives params (from :id segments), query, the JSON-parsed body, and headers — including the authorization header your getToken added. A mocked request goes through the same interceptors as a real one.

Step 3 — A live SSE feed

Set sse: true and write an async generator. Each value you yield becomes one event:

export async function* streamMarketTicksMock({ query, signal }: MockRequest) {
  const symbol = query.get('symbol') ?? 'BTC'
  let price = 67_250
  try {
    while (!signal?.aborted) {
      price += (Math.random() - 0.5) * 50
      yield { symbol, price: Math.round(price), at: Date.now() }
      await new Promise((resolve) => setTimeout(resolve, 1000))
    }
  } finally {
    console.log('ticks stream closed') // runs when the client unsubscribes
  }
}

{ path: '/market/ticks', sse: true, handler: streamMarketTicksMock },

Subscribe the usual way:

const { data: tick, status } = useSse<Tick>('/market/ticks', { query: { symbol: 'BTC' } })

When the component unmounts, the stream closes and the generator's finally block runs — no leaking mock timers.

💡 An SSE route can share a path with a plain GET route. api.sse('/market/ticks') only matches the sse: true route; api.get('/market/ticks') matches the other.

Step 4 — A streaming NDJSON response

AI endpoints often stream JSON lines. A normal route whose handler is an async generator is streamed as NDJSON to api.stream():

{
  method: 'POST',
  path: '/market/summary',
  handler: async function* ({ body }) {
    const { symbol } = body as { symbol: string }
    const words = `${symbol} is trading above its weekly average on strong volume.`.split(' ')
    for (const word of words) {
      yield { token: `${word} ` }
      await new Promise((resolve) => setTimeout(resolve, 80))
    }
  },
},

let text = ''
for await (const { token } of api.stream<{ token: string }>('/market/summary', {
  body: { symbol: 'BTC' },
})) {
  text += token
  setSummary(text)
}

Step 5 — A WebSocket room

WebSocket routes get a tiny server-side connection: send, close and onMessage. Return a function to clean up when the socket closes.

{
  ws: true,
  path: '/rooms/:room',
  handler: (connection, { params }) => {
    connection.send({ type: 'system', text: `Welcome to #${params.room}` })

    connection.onMessage((message) => {
      const { text } = message as { text: string }
      connection.send({ type: 'message', from: 'you', text })
      setTimeout(() => connection.send({ type: 'message', from: 'bot', text: `echo: ${text}` }), 400)
    })

    const presence = setInterval(
      () => connection.send({ type: 'presence', online: 3 + Math.floor(Math.random() * 5) }),
      5000,
    )
    return () => clearInterval(presence)
  },
},

const socket = api.ws('/rooms/:room', {
  params: { room: 'btc' },
  onMessage: (event) => addEvent(event as ChatEvent),
})

socket.send({ text: 'gm' }) // queued until open, then delivered to onMessage

Want to test reconnects? Call connection.close(1011). Any code other than 1000 makes the client back off and reconnect, which runs your handler again.

Step 6 — Errors and latency

The happy path is the easy part. Return a Response to test the rest:

let calls = 0

export const routes: MockRoute[] = [
  // flaky endpoint: first call fails with 503 (retried with plugins: ['retry-idempotent'])
  {
    method: 'GET',
    path: '/portfolio',
    handler: () =>
      ++calls === 1
        ? new Response('Service Unavailable', { status: 503 })
        : { total: 12_400, positions: 4 },
  },
  // rate limit: your onTooManyRequests handler and parseRetryAfter see it
  {
    method: 'POST',
    path: '/orders',
    delayMs: 800,
    handler: () =>
      Response.json({ message: 'Slow down' }, { status: 429, headers: { 'retry-after': '2' } }),
  },
  // session expired: your onUnauthorized / refresh-token logic runs
  {
    method: 'GET',
    path: '/me',
    handler: ({ headers }) =>
      headers.get('authorization') === 'Bearer fresh'
        ? { name: 'Ada' }
        : Response.json({ message: 'expired' }, { status: 401 }),
  },
]

Because mocks replace only the transport, every status handler, retry policy and plugin runs exactly as it would against the real server. You test the code you'll ship.

Step 7 — Switch to the real API, one route at a time

The backend ships /market/overview first. Turn that one mock off and keep the rest:

{ method: 'GET', path: '/market/overview', handler: getMarketOverviewMock, enabled: false },

enabled is read on every request, so you can flip it at runtime — for example from a small dev panel:

routes.forEach((route) => {
  route.enabled = devPanel.isMocked(route.path)
})

When the last route is off, delete the mocks folder. Your components and queries don't change.

Bonus: keep fixtures out of production

A static import puts tanstack-fetch/mock and every fixture in your production bundle, even with enabled: false. Move createMocks into the mocks folder and load it behind the flag so the bundler drops both:

// src/mocks/index.ts
import { createMocks } from 'tanstack-fetch/mock'
export const mocks = createMocks({ delayMs: 250, routes })

// src/lib/api.ts
const mocks =
  import.meta.env.VITE_USE_API_MOCK === 'true' ? (await import('../mocks')).mocks : undefined

export const api = createFetch({ baseUrl, getToken, mocks })

Bonus: reuse the same mocks in tests

Routes are plain objects, so they drop straight into Vitest:

import { createFetch } from 'tanstack-fetch/live'
import { createMocks } from 'tanstack-fetch/mock'
import { routes } from '../src/mocks'

it('renders the overview', async () => {
  const api = createFetch({ baseUrl: 'https://api.test', mocks: createMocks({ routes }) })
  const overview = await api.get('/market/overview')
  expect(overview.markets).toHaveLength(2)
})

Cheat sheet

Need	Route
REST response	`{ method, path, handler: () => data }`
Error / custom status	`handler: () => new Response(…, { status })`
Live events (SSE)	`{ path, sse: true, handler: async function* }`
Streaming JSON (NDJSON)	`{ method, path, handler: async function* }`
WebSocket	`{ ws: true, path, handler: (connection) => … }`
Slow network	`delayMs` on the route or on `mocks`
Turn one mock off	`enabled: false`
Turn every mock off	`createMocks({ enabled: false, … })`

TanStack Start + tanstack-fetch: 6 data fetching patterns

Mohammad Garmabi — Sat, 07 Nov 2026 09:09:44 +0000

Originally published at https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-start-1-0-tanstack-fetch-6-real-world-patterns

TanStack Start is officially stable. If you have been waiting for the 1.0 release before building a production application, now is a good time to explore the framework.

But getting a full-stack React application running is only the first step. The more interesting engineering decisions come later:

Where should an API request run: in a route loader, on the server, or in the browser?
How do you avoid fetching the same data twice?
How should server-side rendering handle cookies and authorization?
How do mutations update the existing Query cache?
What happens when an API returns an HTTP error?
How can a page combine REST data with live server-sent events?

In this tutorial, we'll explore these scenarios using TanStack Start, TanStack Router, TanStack Query, and tanstack-fetch.

I'm the creator of tanstack-fetch, an HTTP client designed to work with TanStack Query's server-state model. It is an independent community package, not an official TanStack project.

1. Start with the right mental model

These libraries solve different problems:

TanStack Start provides the full-stack application framework, including server rendering and server functions.
TanStack Router coordinates routes, navigation, search parameters, and loaders.
TanStack Query manages server-state caching, freshness, mutations, and background updates.
tanstack-fetch handles HTTP requests, typed responses and errors, and reusable request behavior.

The important distinction is that an HTTP client and a server-state manager should not compete for the same responsibilities.

TanStack Query owns the cache. The HTTP client executes requests.

2. Pattern one: Fetch data directly

Not every request needs a complicated abstraction.

For a simple client-side request, create a reusable API client:

import { createFetch } from 'tanstack-fetch'

export const api = createFetch({
  baseUrl: '/api',
})

Then use it in a component or a query function:

import { useQuery } from '@tanstack/react-query'
import { api } from '~/lib/api'

type User = {
  id: string
  name: string
}

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

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

  if (usersQuery.isError) {
    return <p>Could not load users.</p>
  }

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

Three details matter here:

The response is typed as User[].
The query function passes Query's AbortSignal to the HTTP client.
HTTP failures should reject the query so Query can represent them through its error state.

Passing the signal also allows an obsolete request to be cancelled when appropriate.

When to use this pattern: Client-side widgets, independent requests, and pages that do not need route-level preloading.

3. Pattern two: Share route loaders and Query cache

This is where TanStack Router and TanStack Query become particularly useful together.

A common implementation fetches data in a loader, then makes another request when the component mounts. Another implementation stores loader data separately from Query's cache.

Instead, define reusable query options:

import { queryOptions } from '@tanstack/react-query'
import { api } from '~/lib/api'

export const usersQueryOptions = queryOptions({
  queryKey: ['users'],
  queryFn: ({ signal }) => api.get<User[]>('/users', { signal }),
  staleTime: 30_000,
})

Use the same options in the route loader and component:

import { createFileRoute } from '@tanstack/react-router'
import { useQuery } from '@tanstack/react-query'
import { usersQueryOptions } from '~/queries/users'

export const Route = createFileRoute('/users')({
  loader: ({ context }) =>
    context.queryClient.ensureQueryData(usersQueryOptions),
  component: UsersPage,
})

function UsersPage() {
  const { data: users } = useQuery(usersQueryOptions)

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

The router must expose the appropriate queryClient through its typed context, and the application must configure the Query provider and, when using SSR, the appropriate Router–Query integration.

The result is a shared contract:

The loader can ensure that data is available before the route renders.
The component reads from the same Query cache.
Other components can reuse the same query options.
Query controls freshness and subsequent refetching.

When to use this pattern: Lists, detail pages, nested routes, dashboards, and resources shared across multiple components.

4. Pattern three: Handle SSR and authenticated requests

Server-side rendering introduces a different problem: the server does not automatically inherit the browser's request context when it calls an external API.

If an upstream API requires the incoming request's cookies or authorization headers, the HTTP client needs an explicit server-side strategy.

tanstack-fetch supports an ssr-forward plugin for forwarding request context.

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

export const createServerApi = (
  apiOrigin: string,
  cookie: string | undefined,
) =>
  createFetch({
    baseUrl: `${apiOrigin}/api`,
    source: 'ssr',
    interceptors: [createSsrForwardInterceptor()],
    incoming: () => ({ cookie }),
  })

This example illustrates the configuration pattern. Obtain the cookie from the actual incoming request using the relevant TanStack Start server API, and create the client in the request's server-side execution context.

For a real application:

Use an absolute API origin on the server.
Read credentials from the incoming request, not from a global variable.
Never expose private environment variables or server-only credentials to the browser.
Avoid sharing user-specific API clients or Query caches across SSR requests.
Forward only the headers that the upstream service actually needs.

When to use this pattern: Personalized SSR pages, authenticated dashboards, and applications whose API uses cookie-based sessions.

5. Pattern four: Mutations and cache invalidation

Fetching data is only half of a data layer. The other half is keeping the UI consistent after writes.

Suppose an application creates a user. The mutation should use the same HTTP client and invalidate the query that represents the user list.

import { useMutation, useQueryClient } from '@tanstack/react-query'
import { api } from '~/lib/api'

type CreateUserInput = {
  name: string
}

type User = {
  id: string
  name: string
}

export function CreateUserButton() {
  const queryClient = useQueryClient()

  const createUser = useMutation({
    mutationFn: (input: CreateUserInput) =>
      api.post<User>('/users', { body: input }),

    onSuccess: () =>
      queryClient.invalidateQueries({
        queryKey: ['users'],
      }),
  })

  return (
    <button
      disabled={createUser.isPending}
      onClick={() => createUser.mutate({ name: 'New user' })}
    >
      {createUser.isPending ? 'Creating...' : 'Create user'}
    </button>
  )
}

The example assumes the application has already configured the appropriate Query provider.

Invalidation marks matching cached queries as stale and allows active queries to refetch according to Query's behavior. It does not blindly replace every cached copy of the data.

For more responsive interfaces, optimistic updates may be appropriate. However, they need a rollback strategy when the mutation fails and careful handling when concurrent updates are possible.

When to use this pattern: Forms, CRUD screens, admin panels, and any UI where a write affects previously fetched data.

6. Pattern five: Centralize HTTP errors and authentication behavior

HTTP errors should have predictable semantics across the application.

A 401 Unauthorized response might indicate that a session has expired. A 403 Forbidden response generally means that the caller is authenticated but lacks permission. A 404 means the resource was not found.

These conditions should not all trigger the same recovery action.

A reusable HTTP client gives you a place to configure error handling and interceptors instead of repeating that logic in every query function.

For example, a refresh-token interceptor can coordinate token refresh and retry eligible failed requests:

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

const api = createFetch({
  baseUrl: '/api',
})

api.use(
  'refresh-token',
  createRefreshTokenInterceptor({
    refresh: async () => {
      // Refresh the session using your authentication flow.
      // Store updated credentials according to your
      // application's security model.
    },
  }),
)

The refresh implementation is application-specific. It must actually obtain and persist or update the new credential before a retry can succeed.

A production implementation should also consider:

Concurrent requests that fail while a refresh is in progress.
Refresh failure and session expiry.
Avoiding recursive refresh requests.
Which HTTP methods are safe to retry.
Cross-tab session changes.
Whether credentials are stored in secure, HttpOnly cookies or another appropriate mechanism.

When to use this pattern: Applications with authentication, protected APIs, consistent error handling, and several features that share the same backend.

7. Pattern six: Combine REST queries with live SSE updates

Some pages need both an initial snapshot and a stream of updates.

Examples include notifications, order tracking, live dashboards, and operational monitoring.

A useful architecture is:

Load the initial resource through REST or another regular API.
Use TanStack Query to cache and manage that resource.
Open a server-sent events connection in the browser.
Update the cache when an event arrives, or invalidate the relevant query when the event is incomplete.

tanstack-fetch provides SSE support through its tanstack-fetch/sse integration.

The exact event handling depends on the shape of your API. For a complete entity update, you may be able to update the cache directly:

queryClient.setQueryData(
  ['order', orderId],
  updatedOrder,
)

If the event only tells you that an order changed, invalidating the query is usually safer:

queryClient.invalidateQueries({
  queryKey: ['order', orderId],
})

An SSE reconnect does not prove that no events were missed. If you need reliable recovery, design the protocol around event IDs, replay or resume support, and a strategy for reconciling the current snapshot.

When to use this pattern: Live dashboards, event-driven interfaces, and pages where server state changes without a user action.

8. What about Server Functions?

TanStack Start Server Functions are useful for server-only logic that your own application invokes across the client/server boundary.

For example, they can wrap a database operation or access server-only environment variables.

They are not interchangeable with a generic HTTP client.

Use a Server Function when the operation belongs to the application's server logic. Use an HTTP client when communicating with a REST API or another HTTP service. Use Server Routes when you need endpoints intended to be called externally or across origins.

If you combine Server Functions with TanStack Query, keep validation, authorization, and cache invalidation explicit. The server boundary does not remove the need for security checks.

9. A practical project structure

One possible structure is:

src/
  lib/
    api.ts
  queries/
    users.ts
    orders.ts
  routes/
    users.tsx
    orders.$orderId.tsx
  components/
    create-user-button.tsx

The exact folders are less important than keeping responsibilities clear:

lib/api.ts owns reusable HTTP configuration.
queries/ owns shared query keys, options, and request functions.
routes/ owns navigation and route-level data requirements.
components/ owns UI behavior and presentation.

For SSR, keep request-specific clients and caches scoped to the request. Do not turn a convenience singleton into a cross-user data leak.

10. How should you choose?

Requirement	Recommended approach
Simple browser request	`createFetch` + `useQuery`
Route-level preloading	`queryOptions` + `ensureQueryData`
Authenticated SSR	Request-scoped client + `ssr-forward`
Writes and stale cached data	`useMutation` + invalidation
Shared HTTP error policy	Client configuration and plugins
Live server updates	SSE + Query cache
Server-only application logic	TanStack Start Server Functions
Public HTTP endpoint	Server Routes or a dedicated API

You do not need to adopt every pattern at once. Start with one API client and shared query options. Add SSR forwarding, mutation strategies, and live updates only when the application needs them.

Final thoughts

TanStack Start 1.0 makes this a good moment to evaluate a full-stack React architecture, but a stable framework does not automatically give you a maintainable data layer.

The important part is choosing clear boundaries: Router coordinates navigation, Query owns server-state caching, the HTTP client owns transport concerns, and the server owns privileged operations.

That's the problem space tanstack-fetch is designed to address. It is not a replacement for TanStack Query or TanStack Start; it is an option for standardizing HTTP behavior alongside them.

Explore the project:

If you're building with TanStack Start, which part of the data layer has required the most work in your project: SSR, authentication, caching, or real-time updates?

React axios vs tanstack-fetch for TanStack Query

Mohammad Garmabi — Sat, 07 Nov 2026 09:07:55 +0000

Originally published at https://mohamadgarmabi.github.io/tanstack-fetch/blog/react-axios-tanstack-fetch

Stack

React 18+ · tanstack-fetch/react · @tanstack/react-query

Most React apps call axios inside useQuery, then stack a .data unwrap, an error mapper and a refresh-token queue on top. Each of those exists only because axios predates the queryFn contract: return data, throw on failure, honor AbortSignal.

That gap shows up as .data unwraps, custom error mappers, and refresh-token races. tanstack-fetch closes it with the same client every other stack uses — via FetchProvider / useFetch when you want context.

TL;DR

If you need…	Prefer
Drop into `useQuery` / `useMutation`	tanstack-fetch
Typed `FetchError` with status + body	tanstack-fetch
SSE with `Authorization` + resume	tanstack-fetch/sse + `useSse`
Huge axios interceptor stack, no Query	axios can stay
Share one client with Vue/Solid/Angular	tanstack-fetch

npm install tanstack-fetch @tanstack/react-query

Mental model

axios returns AxiosResponse. TanStack Query wants the body and a thrown error. Bridging is possible — and noisy.

Flow: Component (hooks · JSX) → React Query (useQuery · cache) → tanstack-fetch (useFetch() · createFetch — data · throw · signal) → API (REST · SSE · tRPC)

Contract that matters for Query:

Success → return the parsed body
HTTP failure → throw (so isError works)
Cancel → pass Query’s signal through

Side-by-side

axios + Query (glue)

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

const UsersPage = () => {
  const { data, error, isPending } = useQuery({
    queryKey: ['users'],
    queryFn: async ({ signal }) => {
      const response = await axios.get<User[]>('/users', { signal })
      return response.data // easy to forget
    },
  })
  // map AxiosError → UI yourself
}

tanstack-fetch + Query (native)

import { FetchProvider, useFetch } from 'tanstack-fetch/react'
import { useQuery } from '@tanstack/react-query'
import { isFetchError } from 'tanstack-fetch'

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

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((u) => <li key={u.id}>{u.name}</li>)}</ul>
}

Bootstrap / wiring

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { FetchProvider } from 'tanstack-fetch/react'
import { createFetch } from 'tanstack-fetch'
import { createAuthInterceptor } from 'tanstack-fetch/plugins'

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

const queryClient = new QueryClient()

export const App = () => (
  <QueryClientProvider client={queryClient}>
    <FetchProvider client={api}>
      <Routes />
    </FetchProvider>
  </QueryClientProvider>
)

Or skip the provider and import a module-level api into every queryFn — FetchProvider is optional.

Comparison graph: where glue accumulates

Rough relative boilerplate (lower is better) — a map of where teams spend time, not a micro-benchmark.

Task	tanstack-fetch	Typical axios path
Query-ready GET	tanstack-fetch (~18%)	axios + .data (~70%)
Typed HTTP errors	FetchError (~22%)	AxiosError map (~65%)
401 refresh + retry	refresh-token plugin (~28%)	interceptor queue (~88%)
SSE + Authorization	useSse (~30%)	EventSource / custom (~95%)
Shared with Vue/Solid	one createFetch (~20%)	rewrite per stack (~88%)

Feature matrix

Capability	tanstack-fetch	axios
Returns body for Query `queryFn`	Yes	Adapt (`.data`)
Throws typed error with status/body	`FetchError`	Partial
Native `AbortSignal`	First-class	Yes (adapt)
Status handlers `401`–`429`	`createStatusInterceptor`	Custom
Refresh token single-flight	Plugin	Custom
Path params typing `:id`	Yes	Manual
Upload + progress	`api.upload()` (`tanstack-fetch/sse`)	Yes
SSE + `Authorization`	`tanstack-fetch/sse`	No
tRPC transport	`tanstack-fetch/trpc`	DIY
Bundle (HTTP core)	3.68KB gzip	Larger

Auth, status handlers, refresh

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

let expiresAt = 0

const api = createFetch({
  baseUrl: '/api',
  interceptors: [
    createAuthInterceptor({ getToken: () => localStorage.getItem('access_token') }),
    createStatusInterceptor({ 403: () => toast.error('Forbidden') }),
  ],
})

api.use(
  'refresh-token',
  createRefreshTokenInterceptor({
    refresh: async () => {
      const body = await api.post<{ accessToken: string; expiresIn: number }>('/auth/refresh', {
        interceptors: { eject: ['refresh-token', 'auth'] },
      })
      localStorage.setItem('access_token', body.accessToken)
      expiresAt = Date.now() + body.expiresIn * 1000
    },
    before: { getExpiresAt: () => expiresAt, skewMs: 60_000 },
    after: { enabled: true },
  }),
)

The plugin keeps one in-flight refresh and retries the failed call — the usual interceptor queue, without the queue code.

Mutations

import { useMutation, useQueryClient } from '@tanstack/react-query'
import { useFetch } from 'tanstack-fetch/react'

const CreateUser = () => {
  const api = useFetch()
  const queryClient = useQueryClient()
  const mutation = useMutation({
    mutationFn: (input: CreateUserInput) => api.post<User>('/users', { body: input }),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
  })
  return <button onClick={() => mutation.mutate({ name: 'Ada' })}>Create</button>
}

Live data: SSE

Browser EventSource cannot set Authorization. tanstack-fetch/sse streams over fetch.

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

const api = createFetch({
  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>{error?.message}</p>
  return (
    <div>
      <p>{status}</p>
      <pre>{JSON.stringify(data, null, 2)}</pre>
      <button type="button" onClick={close}>Stop</button>
    </div>
  )
}

FetchProvider is not required for SSE — pass { client }.

Status: connecting | connected | disconnected | error.

connecting → connected → onMessage → data → close / unmount

tRPC over the same client

import { createTRPCOptionsProxy } from '@trpc/tanstack-react-query'
import { useQuery, QueryClient } from '@tanstack/react-query'
import { createTRPCClient, httpBatchLink } from '@trpc/client'
import { createTRPCFetch } from 'tanstack-fetch/trpc'
import { api } from './api'
import type { AppRouter } from './server'

const queryClient = new QueryClient()
const trpcClient = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: '/api/trpc', fetch: createTRPCFetch(api) })],
})
const trpc = createTRPCOptionsProxy<AppRouter>({ client: trpcClient, queryClient })

useQuery(trpc.post.list.queryOptions())

Migrate

npx tanstack-fetch migrate --from axios --framework react --write
npx tanstack-fetch doctor --dir ./src

One createFetch (+ optional FetchProvider)
Port useQuery reads first
Port mutations
Swap custom 401 refresh for the plugin
Delete axios when call sites are gone

Suggested folder layout

src/
  lib/api.ts
  queries/users.ts
  components/UsersPage.tsx
  components/OrdersLive.tsx
  App.tsx          # QueryClientProvider + FetchProvider

Decision tree

Is TanStack Query your source of truth for server state?
- Yes → start with tanstack-fetch
- No → axios may stay
Do you need SSE with Authorization or resume?
- Yes → tanstack-fetch/sse + useSse
- No → either client works for simple REST
Do other frameworks share this backend client?
- Yes → one createFetch across packages
- No → still fine; adapters are optional

Checklist

[ ] Optional FetchProvider or shared api module
[ ] Every queryFn / mutationFn forwards { signal }
[ ] Errors via isFetchError when you need status
[ ] Refresh via plugin
[ ] SSE from tanstack-fetch/sse when auth matters
[ ] npx tanstack-fetch doctor --dir ./src clean

Try it

npm install tanstack-fetch @tanstack/react-query
npx tanstack-fetch doctor --dir ./src

Series

Same deep-dive format for every stack:

tanstack-fetch 2.1.0: abortable retries, safer token refresh

Mohammad Garmabi — Sat, 07 Nov 2026 09:07:30 +0000

Originally published at https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-2-1-0

2.1.0 is a fix-first release. No breaking changes. Upgrade and you get:

Cancel means cancel: aborting during a retry delay rejects immediately
Literal colons in paths: /models/gemini:generateContent no longer asks for a generateContent param
One refresh per rotation: a late 401 no longer starts a second refresh
Array query values, parseAs: 'arrayBuffer' | 'stream' and a tanstack-fetch/full entry

Upgrade

npm install tanstack-fetch@2.1.0

Fixed

Cancelling during a retry delay

With Retry-After: 5 (or any backoff), an HTTP request waited out the whole delay even after its signal was aborted. TanStack Query aborts on unmount and on queryKey change, so the query stayed pending for seconds. The delay now listens to your signal and rejects with AbortError immediately, without sending the next attempt.

useQuery({
  queryKey: ['report', id],
  // unmount during a 5s Retry-After → rejects now, no second fetch
  queryFn: ({ signal }) => api.get('/reports/:id', { params: { id }, signal }),
})

Colons inside a path segment

:name is now a path param only at the start of a segment, both at runtime and in the types:

await api.post('/v1/models/gemini:generateContent', { body }) // literal path, no params
await api.get('/users/:id', { params: { id: 1 } }) // → /users/1

Before, the first call threw missing path param "generateContent" and TypeScript asked for that param too.

Refresh token: no second refresh on a late 401

The interceptor already shared one in-flight refresh between parallel 401s. But a request sent with the old token whose 401 arrived after the refresh had finished started a new refresh. With rotating refresh tokens, that second call can invalidate the session the first one just created.

The interceptor now knows which refresh each request was sent after. A late 401 just resends the request with the new token:

A ──(old token)──────────────────────► 401 → retry with new token ✓
B ──(old token)──► 401 → refresh() ✓ → retry ✓
                       refresh() called once

It also fixes the reverse case. A request that was retried for another reason (say a 502 through retry-idempotent) and then got a 401 used to skip the refresh, because the check was attempt > 0. Each request now refreshes at most once, tracked per call, so 401 → refresh → 401 still can't loop.

This works through a new context.meta.state, a plain object shared by every retry attempt of one request. Your own interceptors can use it for per-call flags too.

Stream bodies are never retried

A ReadableStream body is consumed by the first attempt, so a retry used to fail with a confusing "locked stream" TypeError. Requests with a stream body now return the real error (FetchError with the 503, etc.) instead of retrying.

Added

Array query values

await api.get('/users', { query: { ids: [1, 2], role: 'admin' } })
// → /users?ids=1&ids=2&role=admin

QueryParams accepts arrays of string | number | boolean, and each item is appended as its own key=value. null and undefined are still skipped.

`parseAs: 'arrayBuffer' | 'stream'`

const bytes = await api.get<ArrayBuffer>('/files/:id', { params: { id }, parseAs: 'arrayBuffer' })
const body = await api.get<ReadableStream<Uint8Array>>('/export', { parseAs: 'stream' })

'stream' returns the raw response.body without reading it.

`tanstack-fetch/full`

The full HTTP client (option shortcuts, upload(), progress events) lived only under tanstack-fetch/sse, which reads oddly when you don't use SSE. tanstack-fetch/full is the same build under a clearer name, and /sse keeps working.

import { createFetch } from 'tanstack-fetch/full'

Correct types for CommonJS

require('tanstack-fetch') now resolves to .d.cts declarations instead of the ESM .d.ts, so TypeScript projects using module: node16 / nodenext with CJS get the correct types. CI now checks every entry with publint and @arethetypeswrong/cli, and runs the tests on Node 20, 22 and 24.

Bundle size

Import	2.0.0	2.1.0
`tanstack-fetch`	3.57KB	3.68KB
`tanstack-fetch/sse`	6.33KB	6.43KB
`tanstack-fetch/live`	8.75KB	8.84KB
`tanstack-fetch/plugins`	1.13KB	1.22KB

About 100 bytes for the fixes above.

Good to know

Timeouts and aborts reject with the platform TimeoutError / AbortError, not FetchError. That has always been true, and it is now stated in the README. Check them with isAbortError(error). See Errors.

Stop adapting axios to TanStack Query: a fetch client built for queryFn

Mohammad Garmabi — Tue, 03 Nov 2026 13:18:39 +0000

TanStack Query doesn't care how you fetch. It only asks one thing of your queryFn: return data, throw on failure, and respect the AbortSignal.

Most HTTP clients don't do that out of the box, so every project grows the same glue.

The usual glue

queryFn: async ({ signal }) => {
  try {
    const res = await axios.get('/users', { signal })
    return res.data
  } catch (e) {
    if (axios.isAxiosError(e) && e.response?.status === 401) {
      await refreshToken() // what if 5 queries hit 401 at once?
      // retry...?
    }
    throw normalizeError(e)
  }
}

Multiply that by every endpoint, add SSR cookie forwarding and an SSE stream that needs an Authorization header, and you have a small framework nobody meant to write.

The same thing with tanstack-fetch

import { createFetch } from 'tanstack-fetch'
import { createAuthInterceptor, createStatusInterceptor } from 'tanstack-fetch/plugins'

export const api = createFetch({
  baseUrl: 'https://api.example.com',
  interceptors: [
    createAuthInterceptor({ getToken: () => localStorage.getItem('access_token') }),
    createStatusInterceptor({ 401: () => logout() }),
  ],
})

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

Returns the parsed body directly
Throws FetchError, and isFetchError(e) gives you status and body, fully typed
Passes signal through, so Query cancellation just works

Typed errors in the UI

const { error } = useQuery(...)
if (isFetchError(error) && error.status === 404) return <NotFound />

Only pay for what you use

Import	What	gzip
`tanstack-fetch`	slim HTTP core	3.57KB
`tanstack-fetch/plugins`	interceptors	1.13KB
`tanstack-fetch/sse`	+ SSE, upload, progress	6.33KB
`tanstack-fetch/react`	provider + hooks	0.99KB

There are also entry points for Vue/Nuxt, Solid, Svelte, Angular, tRPC and a DevTools dock.

SSE with auth

The browser's EventSource can't send headers. tanstack-fetch/sse can:

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

const api = createFetch({
  baseUrl: 'https://api.example.com',
  getToken: () => localStorage.getItem('access_token'),
})

const stream = api.sse<OrderEvent>('/orders/stream', {
  onMessage: (data) => console.log(data),
})

stream.close()

Migrating

npx tanstack-fetch doctor

It scans your project and scaffolds a migration from axios, ky or ofetch.

Your SSE Connection Dropped. Now What? Building Resumable Server-Sent Events in JavaScript

Mohammad Garmabi — Tue, 03 Nov 2026 11:39:04 +0000

TL;DR — SSE reconnects are easy; recovering the events you missed is not. The fix is id + Last-Event-ID on the client and replay on the server. Below: the problem, the protocol, a minimal Node.js replay server, and a fetch-based client that resumes automatically.

Real-time applications depend on continuous data streams. Whether you're building live dashboards, order tracking systems, notification services, or AI-powered applications, Server-Sent Events (SSE) provide a simple way to push updates from the server to the client.

But there's one problem that is easy to overlook:

What happens when the connection drops?

Imagine you're monitoring an order:

Order created       → Event 101
Payment confirmed   → Event 102
Order processing    → Event 103
Connection lost     → ❌
Order shipped       → Event 104
Order delivered     → Event 105

When the client reconnects, how does it know what happened while it was offline?

Let's explore the problem, understand the SSE protocol, and implement a solution — with and without automatic SSE resume.

1. Understanding the problem

SSE is a one-way communication mechanism over HTTP. The server sends events to the client, and the connection stays open while events are being delivered.

A basic SSE event looks like this:

id: 101
event: order-updated
data: {"status":"created"}

The id field is important. It gives the event a unique identifier that can be used to resume a stream later.

However, receiving events over a persistent connection doesn't automatically mean your application can recover every event after a disconnection. There are two separate concerns:

Reconnecting to the server.
Recovering events that were missed during the disconnection.

The second one requires cooperation between the client and the server.

2. SSE without automatic resume

Let's start with a typical fetch-based streaming implementation (common when you need custom headers like Authorization, which native EventSource doesn't support):

const response = await fetch('/api/orders/stream', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
})

if (!response.body) {
  throw new Error('ReadableStream is not supported')
}

const reader = response.body.getReader()
const decoder = new TextDecoder()

while (true) {
  const { done, value } = await reader.read()
  if (done) break

  const chunk = decoder.decode(value, { stream: true })
  console.log(chunk)
}

This consumes a stream, but it provides no automatic reconnection and no event replay. If the connection drops, your application needs to implement:

Connection state management
Reconnection logic
Tracking the last processed event ID
Sending the last event ID when reconnecting
Handling duplicate events
Retry delays and cancellation

You can build all of this yourself, but the complexity grows fast.

3. Understanding `Last-Event-ID`

Fortunately, SSE already defines a mechanism for resuming a stream: the Last-Event-ID header.

When an SSE event contains an ID:

id: 103
data: {"status":"processing"}

the browser's native EventSource remembers that ID. When the connection is interrupted and it automatically reconnects, it sends:

Last-Event-ID: 103

The server can then replay everything after event 103:

Client received: 101, 102, 103
Connection lost
Client reconnects with Last-Event-ID: 103

Server replays: 104, 105, 106

⚠️ This is the key distinction: the protocol gives you the identifier and the reconnect mechanism — your server must implement event storage and replay.

4. The server side: a minimal replay server (Node.js)

Here's a small, dependency-free example that stores recent events in memory and replays them based on Last-Event-ID:

import http from 'node:http'

const history = []          // [{ id, event, data }]
const clients = new Set()
let nextId = 1
const MAX_HISTORY = 1000

function format({ id, event, data }) {
  return `id: ${id}\nevent: ${event}\ndata: ${JSON.stringify(data)}\n\n`
}

function publish(event, data) {
  const msg = { id: nextId++, event, data }
  history.push(msg)
  if (history.length > MAX_HISTORY) history.shift()
  for (const res of clients) res.write(format(msg))
}

http.createServer((req, res) => {
  if (req.url !== '/orders/stream') return res.writeHead(404).end()

  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    Connection: 'keep-alive',
  })
  res.write('retry: 3000\n\n') // suggested reconnect delay

  // 1) Replay what the client missed
  const lastId = Number(req.headers['last-event-id'] ?? 0)
  for (const msg of history) {
    if (msg.id > lastId) res.write(format(msg))
  }

  // 2) Keep streaming new events
  clients.add(res)
  req.on('close', () => clients.delete(res))
}).listen(3000)

// Demo: emit an order update every 2s
setInterval(() => publish('order-updated', { status: 'tick', at: Date.now() }), 2000)

In production you'd replace the in-memory array with Redis Streams, Kafka, a database table, or anything that gives you ordered, durable IDs.

5. Automatic SSE resume on the client with tanstack-fetch

Instead of implementing reconnection and event ID tracking manually, you can use the sse-resume plugin in tanstack-fetch.

Configure your client:

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

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

Consume your stream with a callback:

const stream = api.sse<OrderEvent>('/orders/stream', {
  onMessage: (data) => {
    console.log('Received:', data)
  },
})

…or with async iteration:

for await (const event of api.sse<OrderEvent>('/orders/stream', { signal })) {
  console.log(event.data)
}

With sse-resume enabled, tanstack-fetch:

✅ Tracks the last received event ID
✅ Sends Last-Event-ID when reconnecting
✅ Automatically resumes after the stream closes

You don't need to build the reconnection and ID-tracking layer yourself — and unlike native EventSource, you keep full control over headers (auth tokens, etc.).

6. Server checklist

Client-side resume is only half of the solution. Your server must:

Assign a stable, ordered ID to each event.
Keep enough event history to support reconnecting clients.
Read the incoming Last-Event-ID header.
Replay events after the supplied ID — not just start from the newest.
Continue sending new events through the same stream.

Also think about event retention, expired IDs (what if the ID is older than your history?), duplicate delivery, and authorization on reconnect.

Important: Resumable delivery is not exactly-once delivery. Use idempotent event processing or deduplication (e.g. by event ID) on the client where it matters.

7. When should you use SSE resume?

SSE resume is particularly useful for:

📦 Live order and shipment tracking
💸 Financial dashboards and transaction updates
🔔 Notification systems
⏳ Long-running background jobs
🤖 AI-generated streaming responses
📊 Monitoring and observability dashboards

Whenever missing an event can leave the client in an inconsistent state, resumability deserves consideration.

Conclusion

SSE makes real-time communication relatively simple, but production systems need to think beyond "open a connection and read events". A reliable implementation should consider reconnection, event IDs, replay, duplicate handling, and cancellation.

You can implement these mechanisms yourself, rely on the browser's native EventSource, or use a fetch-based solution with automatic resume support.

If you're already using tanstack-fetch, enabling sse-resume is one line:

plugins: ['sse-resume']

📚 Docs & implementation: https://mohamadgarmabi.github.io/tanstack-fetch/recipes/sse-resume

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

💬 How do you handle dropped real-time connections in your apps — SSE, WebSockets, or polling? I'd love to hear your approach in the comments. If this was useful, a ❤️ or a 🦄 helps others find it!

tanstack-fetch 2.0.0: A Smaller Core, WebSockets, WebTransport, and Type-Safe Streams

Mohammad Garmabi — Sat, 31 Oct 2026 08:24:09 +0000

From a lightweight HTTP client to a modular transport layer for modern TypeScript applications.

Today, I'm releasing tanstack-fetch 2.0.0.

This is more than another feature release. Since v1.7.1, tanstack-fetch has evolved beyond traditional HTTP requests. It now supports multiple communication transports, including WebSockets, WebTransport, and NDJSON streams, while keeping its familiar API and TypeScript-first approach.

Version 2.0.0 also brings an important architectural change: a significantly smaller HTTP core, with optional functionality moved into dedicated plugins.

Let's look at what changed and why.

What's new since v1.7.1?

The journey from 1.7.1 to 2.0.0 includes two releases:

v1.8.0: Introduced new live communication transports.
v2.0.0: Refactored the core architecture and improved type safety for live APIs.

Let's break them down.

1. WebSocket support

HTTP isn't always the right transport.

Applications such as chat systems, collaborative tools, dashboards, and real-time applications often need persistent, bidirectional communication.

In v1.8.0, I introduced api.ws().

It provides WebSocket communication through the same client architecture used by HTTP.

import { createFetch } from 'tanstack-fetch'

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

const socket = api.ws<Message, { roomId: string }, SendMessage>(
  '/rooms/:roomId',
  {
    params: { roomId: 'general' },
  },
)

socket.onMessage((message) => {
  console.log(message)
})

socket.send({
  text: 'Hello!',
})

Key capabilities include:

Automatic reconnection with exponential backoff.
Fresh authentication tokens on reconnection attempts.
Ordered message queuing until the connection opens.
JSON message parsing.
AbortSignal support.
Connection lifecycle callbacks.
Integration with the shared interceptor architecture.

Authentication is also designed with platform differences in mind. Node.js 22+, Bun, and Deno support Authorization headers. Browsers and workers can explicitly use query or protocol-based authentication when needed.

Tokens are never placed in URLs by default.

2. WebTransport support

WebSocket isn't the only option for persistent communication.

Version 1.8.0 also introduced api.transport() for WebTransport.

WebTransport provides an HTTP/3-based transport with support for datagrams and other communication patterns.

const connection = api.transport('/live', {
  // WebTransport-specific options
})

The API supports WebTransport-specific configuration, including serverCertificateHashes, and a createWebTransport option for environments that need a custom implementation or polyfill.

This makes it possible to work with different transport technologies without building an entirely separate client architecture.

3. NDJSON streaming with api.stream()

Another major addition is api.stream().

It supports NDJSON (Newline Delimited JSON), allowing a server to send JSON objects incrementally instead of waiting for an entire response.

const stream = api.stream<Message>('/events', {
  method: 'POST',
  body: {
    prompt: 'Explain how streaming works',
  },
})

for await (const message of stream) {
  console.log(message)
}

Unlike a conventional JSON response, NDJSON can be consumed progressively.

The implementation also supports:

Any HTTP method and request body.
The shared interceptor pipeline.
Status handlers and authentication refresh.
Retry behavior.
AbortSignal cancellation.
Integration with TanStack Query's streamedQuery.

It also handles Node.js streaming requirements by setting duplex: 'half' for ReadableStream request bodies.

4. A unified live transport architecture

With WebSocket, WebTransport, and NDJSON support, managing live communication separately from HTTP would create unnecessary complexity.

That's why these transports share the same underlying client architecture.

Version 1.8.0 introduced a dedicated entry point:

import { createFetch } from 'tanstack-fetch/live'

It exposes:

api.sse()
api.ws()
api.transport()
api.stream()

The existing tanstack-fetch/sse entry point remains unchanged and lightweight.

The shared architecture also introduces live-specific interceptor hooks:

onLiveOpen
onLiveMessage
onLiveClose

These callbacks make it possible to observe incoming and outgoing messages and connection lifecycle events.

The transport type is available through:

context.meta.transport

Possible values include websocket, webtransport, and ndjson.

5. DevTools improvements

Debugging live communication can be difficult, especially when multiple connections and messages are involved.

Version 1.8.0 extends DevTools with dedicated tabs:

WS: WebSocket and WebTransport connections.
Stream: NDJSON streams.

Each connection includes a message log, making it easier to inspect communication during development.

The CLI also gained improvements:

generate can generate api.stream for NDJSON operations.
doctor detects raw new WebSocket and new EventSource usage.
It checks whether api.stream correctly receives an AbortSignal inside queryFn.

6. A smaller HTTP core in v2.0.0

Now comes one of the most important changes.

The core package has been reduced from 5.14 KB to 3.57 KB gzip.

That's approximately a 30% reduction.

The goal isn't to remove functionality from the ecosystem. It's to keep the HTTP core focused and move optional functionality into dedicated modules.

The core createFetch configuration now focuses on:

baseUrl
headers
source
incoming
timeoutMs
interceptors
fetch
credentials
maxRetries

Authentication and status handling are now provided through dedicated interceptors.

For example:

import { createFetch } from 'tanstack-fetch'
import {
  createAuthInterceptor,
  createStatusInterceptor,
} from 'tanstack-fetch/plugins'

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

  interceptors: [
    createAuthInterceptor({
      getToken: () => getAccessToken(),
    }),

    createStatusInterceptor({
      401: async () => {
        // Handle unauthorized responses
      },

      '5xx': async () => {
        // Handle server errors
      },
    }),
  ],
})

This is a more composable architecture.

Instead of making every application carry authentication and status-handling functionality in its core configuration, developers can explicitly add the behavior they need.

Other interceptors, such as tracing and token refresh, can also be composed through the plugin architecture.

What moved out of core?

The following functionality is no longer part of the core createFetch API:

getToken
auth
plugins: [...]
onStatus
onUnauthorized
onForbidden
Other status shortcut callbacks
upload()
XHR-based upload and download progress events

The important distinction is that this is a change to the core HTTP client, not a removal of these capabilities from the entire library.

The tanstack-fetch/sse, /live, /trpc, and framework provider entry points retain their existing options, upload functionality, and progress events.

For applications relying on the previous upload API, switching to tanstack-fetch/sse provides a drop-in upgrade path.

7. Type-safe parameters for live APIs

Version 2.0.0 also brings an important TypeScript improvement.

Previously, live transport APIs didn't offer the same path-parameter inference available in HTTP methods.

Now, live APIs support typed route parameters.

const socket = api.ws<Message, { roomId: number }>(
  '/rooms/:roomId',
  {
    params: {
      roomId: 42,
    },
  },
)

The same approach is available across:

api.sse()
api.ws()
api.transport()
api.stream()
useSse()
useWs()

Framework bindings now support this improvement across React, Vue, Solid, Svelte, and Angular.

The generic parameter order has also been aligned with the HTTP API:

// WebSocket
<Message, Params, Send>

// SSE / NDJSON
<Message, Params>

If you previously used the old WebSocket generic order, you'll need to update your type arguments. Use NoParams when you don't need route parameters.

New exported types include:

LiveParams
FetchMethodPath
FetchParamsConstraint

The OpenAPI generate command also emits parameter types for SSE and NDJSON operations.

8. Important bug fixes

Version 2.0.0 also includes improvements to the NDJSON streaming lifecycle.

Node.js ReadableStream request bodies

api.stream() now sends duplex: 'half' when a ReadableStream is used as a request body, as required by Node.js/undici.

Network errors

Network failures now correctly trigger onRequestError, allowing retry or short-circuit behavior.

Abort during retry delay

Aborting a stream during a retry delay now rejects immediately instead of waiting for the delay to finish.

9. Migration from 1.7.1 to 2.0.0

Because 2.0.0 introduces breaking changes, upgrading requires reviewing your client configuration.

Step 1: Update the package

npm install tanstack-fetch@2.0.0

Step 2: Move authentication and status handlers to interceptors

If your previous configuration looked like this:

const api = createFetch({
  baseUrl: '/api',
  getToken,
  onUnauthorized: handleUnauthorized,
})

Move those responsibilities into the plugin architecture:

import {
  createAuthInterceptor,
  createStatusInterceptor,
} from 'tanstack-fetch/plugins'

const api = createFetch({
  baseUrl: '/api',

  interceptors: [
    createAuthInterceptor({ getToken }),

    createStatusInterceptor({
      401: handleUnauthorized,
    }),
  ],
})

Step 3: Review upload usage

The core client no longer exposes upload() or XHR progress callbacks.

If you depend on these features, use the tanstack-fetch/sse entry point, which retains the previous upload functionality.

Step 4: Update WebSocket generic arguments

If you used the previous generic order:

api.ws<Message, Send>('/rooms/:id')

Update it to:

api.ws<Message, { id: number }, Send>(
  '/rooms/:id',
  {
    params: { id: 1 },
  },
)

Review other live APIs for the new typed params argument as well.

What's next?

The direction behind tanstack-fetch is becoming clearer.

I don't want to build another library that simply wraps fetch() with a different syntax.

The goal is to provide a predictable, type-safe transport layer that works naturally with TanStack Query and modern TypeScript applications.

HTTP, SSE, WebSockets, WebTransport, and NDJSON are different communication mechanisms, but they shouldn't require completely different approaches to authentication, error handling, observability, and cancellation.

With v2.0.0, the foundation is smaller, the architecture is more modular, and live communication is more consistent.

tanstack-fetch 2.0.0 is available now.

npm install tanstack-fetch

Project links

Documentation: https://mohamadgarmabi.github.io/tanstack-fetch/
GitHub: https://github.com/mohamadgarmabi/tanstack-fetch
npm: https://www.npmjs.com/package/tanstack-fetch
Release notes: https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-2-0-0

I'm the creator and maintainer of tanstack-fetch. This is an independent open-source project, not an official TanStack package.

I'd love to hear your feedback, especially from developers building applications with real-time data and TanStack Query.

Stop Sending Too Many API Requests in React: 6 TanStack Pacer Patterns

Mohammad Garmabi — Wed, 28 Oct 2026 07:20:36 +0000

If your React app feels slow, the problem might not be the HTTP client.

It might be that you're sending requests too often.

A search box can fire on every keystroke. Autosave can create overlapping mutations. Infinite scrolling can trigger repeated calculations. Bulk uploads can overwhelm an API. Analytics can generate dozens of small requests.

TanStack Pacer helps control when and how frequently work runs. Combine it with TanStack Query and tanstack-fetch to separate timing, caching, and HTTP transport.

I'm the creator of tanstack-fetch, an independent community project—not an official TanStack package.

The architecture

Concern	Tool
Debounce, throttle, queue, batch, rate-limit	TanStack Pacer
Server-state cache and query lifecycle	TanStack Query
HTTP requests and typed errors	tanstack-fetch

Install the packages:

npm install @tanstack/react-pacer @tanstack/react-query tanstack-fetch

Create a shared client:

import { createFetch } from 'tanstack-fetch'

export const api = createFetch({
  baseUrl: import.meta.env.VITE_API_URL,
  timeoutMs: 10_000,
})

The following snippets illustrate the intended patterns. Verify API signatures against the versions installed in your project.

1. Debounce search without breaking Query

Debounce the value that goes into the query key, not the queryFn.

import { useState } from 'react'
import { useDebouncedValue } from '@tanstack/react-pacer'
import { keepPreviousData, useQuery } from '@tanstack/react-query'
import { api } from '~/lib/api'

export function SearchUsers() {
  const [search, setSearch] = useState('')
  const [debouncedSearch] = useDebouncedValue(search, {
    wait: 300,
  })

  const query = useQuery({
    queryKey: ['users', 'search', debouncedSearch],
    queryFn: ({ signal }) =>
      api.get<User[]>('/users', {
        query: { q: debouncedSearch },
        signal,
      }),
    enabled: debouncedSearch.trim().length >= 2,
    placeholderData: keepPreviousData,
    staleTime: 30_000,
  })

  return (
    <>
      <input
        value={search}
        onChange={(event) => setSearch(event.target.value)}
      />
      {query.isFetching && <span>Searching...</span>}
      {query.data?.map((user) => (
        <div key={user.id}>{user.name}</div>
      ))}
    </>
  )
}

The input remains responsive. Query receives settled search terms, caches results per key, and can cancel obsolete requests when the query function consumes its signal.

2. Autosave with an abortable request

Autosave needs more than a delay. It needs a strategy for pending edits, in-flight requests, and cache synchronization.

The pattern is:

Debounce the save operation.
Pass an AbortSignal to the HTTP request.
Cancel pending work when the user discards a draft.
Update the Query cache after a successful response.

With Pacer's async debouncer, the core request can look like this:

const saveNote = async (draft: NoteDraft, signal: AbortSignal) =>
  api.patch<Note, { id: string }, NoteDraft>(
    '/notes/:id',
    {
      params: { id },
      body: draft,
      signal,
    },
  )

Connect this function to useAsyncDebouncer, use its cancellation APIs for discarded work, and update ['notes', id] with the returned server record.

Important: browser cancellation doesn't guarantee that the server never processed a request. For sensitive edits, use server-side version checks or optimistic concurrency.

3. Throttle infinite scrolling

Scroll handlers can execute dozens of times per second. Throttling limits how often you calculate whether the user is near the bottom.

const onScroll = useThrottledCallback(
  (element: HTMLElement) => {
    const nearBottom =
      element.scrollTop + element.clientHeight >
      element.scrollHeight - 600

    if (nearBottom && hasNextPage && !isFetchingNextPage) {
      void fetchNextPage()
    }
  },
  { wait: 200 },
)

TanStack Query should still own pagination and request state. Pacer limits the frequency of the event-driven work. An IntersectionObserver is another option for sentinel-based infinite scrolling.

4. Rate-limit calls before they hit the API

For an API with a quota of five calls per second, a client-side limiter can prevent avoidable calls.

const limiter = useAsyncRateLimiter(
  (address: string) =>
    api.get<Place[]>('/geocode', {
      query: { address },
    }),
  {
    limit: 5,
    window: 1_000,
    windowType: 'sliding',
    onReject: (_args, rateLimiter) => {
      const seconds = Math.ceil(
        rateLimiter.getMsUntilNextWindow() / 1000,
      )
      toast(`Try again in ${seconds}s`)
    },
  },
)

This improves the client experience, but it is not a security boundary. The server must enforce its own quota.

For HTTP 429 responses, transport-level handling can respect Retry-After:

import { createFetch, parseRetryAfter } from 'tanstack-fetch'

const api = createFetch({
  baseUrl: import.meta.env.VITE_API_URL,
  maxRetries: 2,
  onTooManyRequests: ({ context }) => ({
    action: 'retry',
    delayMs: parseRetryAfter(context.response?.headers, 1_000),
  }),
})

5. Queue uploads with bounded concurrency

Don't open 200 simultaneous uploads just because the user selected 200 files.

const queue = useAsyncQueuer(
  (job: UploadJob) =>
    api.upload<Photo>('/photos', {
      file: job.file,
      fields: { albumId: job.albumId },
    }),
  {
    concurrency: 3,
    wait: 100,
    onSuccess: (_photo, job) =>
      queryClient.invalidateQueries({
        queryKey: ['albums', job.albumId, 'photos'],
      }),
    onError: (error, job) =>
      console.error(`Upload failed: ${job.file.name}`, error),
  },
)

A bounded queue provides backpressure: only a few requests run at once, and the rest wait. Add progress indicators, retry policy, and per-file status for a production implementation.

6. Batch analytics events

Sending each analytics event separately adds request overhead.

const batcher = useAsyncBatcher(
  (events: TrackEvent[]) =>
    api.post('/events', { body: { events } }),
  {
    maxSize: 20,
    wait: 2_000,
    onError: (error, batch) =>
      console.warn(`Batch of ${batch.length} events failed`, error),
  },
)

batcher.addItem({
  name: 'button_clicked',
  at: Date.now(),
  props: { page: 'dashboard' },
})

This batches events by size or elapsed time. In production, consider event deduplication and how pending events should be flushed when a page becomes hidden.

Don't retry at every layer

Retries can be configured in Query, Pacer, and the HTTP client. If all three independently retry the same operation, a single failure can multiply into many requests.

A useful division:

HTTP status-aware retry behavior belongs at the transport layer.
Query retries belong to query lifecycle policy.
Pacer retries should be enabled deliberately for queued or batched tasks.

For example:

import { isFetchError } from 'tanstack-fetch'

retry: (count, error) =>
  !(isFetchError(error) && error.status < 500) &&
  count < 3

Adjust the policy to your API. Not every 4xx response should be treated the same way.

Quick reference

Use case	Pacer utility
Search input	`useDebouncedValue`
Autosave	`useAsyncDebouncer`
Scroll handlers	`useThrottledCallback`
API quota	`useAsyncRateLimiter`
Upload concurrency	`useAsyncQueuer`
Analytics	`useAsyncBatcher`

The takeaway

Pacer controls timing. Query controls server state. tanstack-fetch handles HTTP transport.

That separation makes the code easier to reason about than mixing debouncing, caching, cancellation, and HTTP error handling into one custom abstraction.

I'm Mohammad Garmabi, creator of tanstack-fetch, an independent community HTTP client.

tRPC + TanStack Router: Build Fully Type-Safe Data Fetching with tanstack-fetch

Mohammad Garmabi — Tue, 27 Oct 2026 14:15:55 +0000

An end-to-end guide to combining tRPC, TanStack Query, TanStack Router, and tanstack-fetch in a modern TypeScript application.

Modern TypeScript applications need more than a convenient way to fetch data. They need reliable API contracts, predictable caching, route-aware data loading, and a clean separation between HTTP transport and server state.

That is where this stack becomes interesting:

tRPC provides end-to-end type safety between your server and client.
tanstack-fetch handles HTTP transport, request configuration, and reusable networking behavior.
TanStack Query manages caching, query state, and background refetching.
TanStack Router coordinates navigation and route-level data loading.

Instead of implementing these concerns independently, we can combine them into a single, consistent data-fetching architecture.

In this tutorial, we'll build a practical example using a post.list procedure.

1. Understand how the pieces fit together

Before writing code, it's important to understand that these libraries solve different problems.

Library	Responsibility
tRPC	Type-safe API procedures and client-server contracts
tanstack-fetch	HTTP transport, interceptors, plugins, and request behavior
TanStack Query	Caching, query lifecycle, and server-state synchronization
TanStack Router	Navigation, route context, and loader execution

The request flow looks like this:

TanStack Router → TanStack Query → tRPC client → tanstack-fetch → tRPC server

The key architectural decision is that TanStack Router doesn't need to know how HTTP requests work. It uses query options through its context, while tanstack-fetch handles the transport layer underneath tRPC.

This separation keeps routing, server state, and networking concerns independent.

2. Install the dependencies

For a React application using TanStack Router and TanStack Query, install the following packages:

npm install tanstack-fetch @trpc/client \
  @trpc/tanstack-react-query \
  @tanstack/react-query \
  @tanstack/react-router

You'll also need your application's tRPC server and its exported AppRouter type.

The examples below assume that your server exposes a procedure at post.list through /api/trpc.

3. Create a shared HTTP client with tanstack-fetch

Start by configuring the HTTP transport.

Create src/lib/trpc.ts:

import { createFetch } from 'tanstack-fetch'
import { createTRPCFetchClient } from 'tanstack-fetch/trpc'
import { createTRPCOptionsProxy } from '@trpc/tanstack-react-query'
import { QueryClient } from '@tanstack/react-query'
import type { AppRouter } from '../server/router'

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

export const queryClient = new QueryClient()

export const trpc = createTRPCOptionsProxy<AppRouter>({
  client: createTRPCFetchClient<AppRouter>({
    url: '/api/trpc',
    client: api,
  }),
  queryClient,
})

Let's break down what's happening.

Why use `createFetch`?

createFetch gives us a reusable HTTP client that can centralize networking behavior instead of scattering it throughout our application.

Depending on your configuration, this is where you can organize concerns such as authentication, error handling, plugins, and request instrumentation.

For example, if multiple API procedures need the same transport-level behavior, you can configure that behavior once rather than reimplementing it for individual queries.

Why use `createTRPCFetchClient`?

tRPC already provides the procedure-based API and type information. createTRPCFetchClient connects that API to the HTTP client created with tanstack-fetch.

The generic AppRouter connects the client to your server's procedure definitions, allowing TypeScript to infer the available procedures and their input and output types.

Why use `createTRPCOptionsProxy`?

This helper from @trpc/tanstack-react-query exposes tRPC procedures as TanStack Query-compatible options.

For example:

trpc.post.list.queryOptions()

Instead of manually maintaining query keys and query functions for every tRPC procedure, you can use the options generated from the typed client.

4. Integrate TanStack Router with query context

Now that the API client exists, we can connect it to the router.

Create or update src/router.tsx:

import { createRouter } from '@tanstack/react-router'
import { QueryClientProvider } from '@tanstack/react-query'
import { queryClient, trpc } from './lib/trpc'
import { routeTree } from './routeTree.gen'

export const router = createRouter({
  routeTree,

  context: {
    trpc,
    queryClient,
  },

  Wrap: ({ children }) => (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  ),
})

The important part is the router context:

context: {
  trpc,
  queryClient,
}

This makes the typed tRPC options and QueryClient available to route loaders.

A loader can now prepare data before the route renders, without importing the API client directly into every route module.

This also makes route dependencies explicit and gives us a consistent pattern to reuse across the application.

5. Fetch data in a route loader

Let's create a posts page.

import { createFileRoute } from '@tanstack/react-router'
import { useQuery } from '@tanstack/react-query'

export const Route = createFileRoute('/posts')({
  loader: ({ context }) =>
    context.queryClient.ensureQueryData(
      context.trpc.post.list.queryOptions(),
    ),

  component: PostsPage,
})

function PostsPage() {
  const { trpc } = Route.useRouteContext()

  const { data, isPending, isError } = useQuery(
    trpc.post.list.queryOptions(),
  )

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

  if (isError) {
    return <p>Failed to load posts.</p>
  }

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

There are two important operations here.

`ensureQueryData` in the loader

loader: ({ context }) =>
  context.queryClient.ensureQueryData(
    context.trpc.post.list.queryOptions(),
  )

The loader asks TanStack Query to ensure that the query has data available before the route proceeds.

If suitable cached data already exists, it can be reused. Otherwise, the query can fetch the data.

This is especially useful when the page depends on server data to provide a meaningful initial render.

`useQuery` in the component

const { data } = useQuery(
  trpc.post.list.queryOptions(),
)

The component subscribes to the same query managed by TanStack Query.

Because the loader and component use the same query options, they share the query's cache identity. You don't need a separate query key or a second manually implemented fetch function.

The result is a consistent data flow from navigation to rendering.

6. What happens when the user navigates to `/posts`?

Here's the lifecycle:

The user navigates to /posts.
TanStack Router runs the route loader.
The loader calls ensureQueryData.
TanStack Query checks its cache and fetches if necessary.
The tRPC client invokes the post.list procedure.
tanstack-fetch handles the HTTP transport.
The server returns the procedure result.
TanStack Query stores the result in its cache.
The route component reads that query through useQuery.

This architecture avoids manually coordinating the router's loading state with a separate data-fetching implementation.

It also allows TanStack Query to manage subsequent updates, refetching, and cache reuse.

One important detail: ensureQueryData doesn't necessarily force a fresh request when cached data exists. If your route needs to revalidate stale data, choose an appropriate freshness policy or use ensureQueryData's revalidateIfStale option where suitable.

7. Why not call tRPC directly inside every component?

You certainly can call tRPC procedures directly. The question is how you want to manage server state.

Consider this approach:

const [posts, setPosts] = useState<Post[]>([])
const [loading, setLoading] = useState(true)

useEffect(() => {
  trpcClient.post.list
    .query()
    .then(setPosts)
    .finally(() => setLoading(false))
}, [])

This is a simplified illustration of manually managing a request. In a larger application, you would also need to account for errors, cancellation, caching, duplicate requests, and component lifecycle behavior.

With TanStack Query, those concerns are handled by a dedicated server-state layer. With tRPC's Query integration, the procedures remain fully typed.

And with tanstack-fetch, transport behavior can remain separate from the component and query logic.

Each tool has a clearly defined responsibility.

8. Where tanstack-fetch adds value

tRPC already provides a powerful client-server contract, so why introduce another HTTP client?

The answer is transport-level consistency.

In an application with multiple API integrations, you may want shared networking behavior for authentication, errors, request instrumentation, and other HTTP concerns.

tanstack-fetch provides a configurable transport layer and a tRPC integration, allowing you to reuse its HTTP behavior while keeping tRPC's procedure types.

For example, the same transport client can be configured with plugins:

import { createFetch } from 'tanstack-fetch'

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

The example uses a configured plugin identifier; the actual plugin must be available in your installed version and project setup.

The objective isn't to add another abstraction for its own sake. It's to keep networking behavior in one place when that centralization provides real value.

If your application only has a tiny tRPC integration and no need for shared HTTP behavior, the simpler native tRPC setup may be sufficient.

9. What about authentication and server-side rendering?

For a browser-only application, a relative URL such as /api/trpc is usually appropriate.

For server-side rendering, the request may need an absolute URL, and authentication cookies or headers may need to be forwarded to the server.

A simplified URL helper looks like this:

const getTrpcUrl = () =>
  typeof window === 'undefined'
    ? `${process.env.SSR_ORIGIN ?? 'http://localhost:3000'}/api/trpc`
    : '/api/trpc'

However, this is only part of a correct SSR setup.

For server rendering, configure the HTTP client with the appropriate SSR behavior, forward only the request-specific credentials that are required, and create request-scoped clients and query caches where necessary. Avoid sharing user-specific authentication state through a global server-side singleton.

For TanStack Start, the official integration recipe demonstrates the combination of tRPC, TanStack Query, router context, and SSR-aware transport configuration.

See the full guide: tRPC + tanstack-fetch.

10. The resulting architecture

The benefit of this approach is not simply fewer lines of code. It is a clearer separation of responsibilities:

TanStack Router determines when route data should be prepared.
TanStack Query manages cached server state and its lifecycle.
tRPC provides typed procedure calls between the client and server.
tanstack-fetch centralizes configurable HTTP transport behavior.

You can evolve each layer without turning every route into a collection of networking, caching, and loading-state decisions.

Final thoughts

TanStack Router, TanStack Query, and tRPC already make a strong foundation for type-safe applications. Adding tanstack-fetch is most useful when you also want a reusable HTTP transport layer with shared networking behavior.

The result is an architecture where route loaders prepare data, query options define how server state is accessed, tRPC maintains end-to-end type safety, and the HTTP layer remains independent of UI components.

The key principle: keep routing, server state, API contracts, and HTTP transport separate — but integrate them through explicit, typed interfaces.

Explore the integration guide: https://mohamadgarmabi.github.io/tanstack-fetch/guide/trpc#trpc

By Mohammad Garmabi — creator of tanstack-fetch, an independent HTTP client for the TanStack ecosystem. Not an official TanStack package.

Your React API Layer Is a Mess. Let's Fix It with TanStack Query and tanstack-fetch

Mohammad Garmabi — Mon, 26 Oct 2026 07:35:09 +0000

A hands-on tutorial for typed API requests, better error handling, cancellation, and server-side rendering in Next.js.

Every React application starts with a few API calls.

You write a fetch, parse some JSON, render a list, and move on.

Then the application grows.

You add authentication. Different endpoints return different errors. Some requests need cancellation. Others need retries. Your Next.js pages fetch data on the server, while client components use TanStack Query. Suddenly, you have multiple API clients, duplicated error handling, and several different ways to send the same HTTP request.

Sound familiar?

The problem isn't that fetch is bad. It's that HTTP transport concerns tend to spread throughout an application when there isn't a clear boundary around them.

In this tutorial, we'll build a reusable API layer using tanstack-fetch, connect it to TanStack Query, and use it in a Next.js App Router application.

By the end, you'll have a practical architecture for queries, mutations, typed errors, request cancellation, and server-side data prefetching.

1. Why does a React API layer become difficult to maintain?

Let's start with a familiar implementation.

async function getUsers() {
  const response = await fetch('/api/users')

  if (!response.ok) {
    throw new Error('Failed to fetch users')
  }

  return response.json()
}

This is perfectly reasonable for a small application.

But now imagine that every API function needs to handle authentication, different error responses, request headers, and cancellation.

You might end up with code like this:

async function getUsers(signal?: AbortSignal) {
  const token = localStorage.getItem('access_token')

  const response = await fetch('/api/users', {
    headers: {
      Authorization: `Bearer ${token}`,
    },
    signal,
  })

  if (response.status === 401) {
    // Handle an expired session.
  }

  if (response.status === 403) {
    // Handle insufficient permissions.
  }

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

  return response.json()
}

Then another developer writes a different implementation for creating users. Someone else adds a third implementation for uploading files.

Over time, the application loses consistency.

The solution isn't to build a massive abstraction that handles every possible situation. It's to establish a small, reusable HTTP contract.

For an application using TanStack Query, that contract should be straightforward:

Successful requests return the response data.
Failed HTTP requests throw an error.
Requests support cancellation through AbortSignal.
Authentication and transport configuration live in a shared client.

That's the approach we'll implement.

2. What is tanstack-fetch?

tanstack-fetch is an open-source TypeScript-first HTTP client built by Mohammad Garmabi.

It is an independent project, not an official TanStack package.

Its central idea is simple: provide an HTTP client that fits naturally into TanStack Query's queryFn and mutationFn contracts.

Instead of repeatedly adapting an HTTP client's response object, your query function can return the data directly.

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

const users = await api.get<User[]>('/users')

When a request fails, the client throws a FetchError. When a request receives an AbortSignal, it can honor cancellation.

The result is a cleaner boundary between HTTP transport and server-state management.

One important distinction:

tanstack-fetch handles HTTP requests. TanStack Query handles server state.

TanStack Query still manages caching, stale data, retries, background refetching, and query lifecycle. You don't need to replace any of those features.

3. Create the project

Let's build a small user-management feature with React, TypeScript, TanStack Query, and Next.js.

Install the dependencies:

npm install tanstack-fetch @tanstack/react-query

We'll use the Next.js App Router and organize the relevant files like this:

src/
├── app/
│   ├── layout.tsx
│   └── users/
│       ├── page.tsx
│       └── users-client.tsx
├── lib/
│   ├── api.ts
│   └── api.server.ts
└── queries/
    └── users.ts

This structure separates three concerns:

lib/ contains HTTP client configuration.
queries/ contains reusable query definitions.
app/ contains server-rendered pages and interactive UI.

You don't need to follow this exact folder structure. The important part is keeping request configuration and query definitions out of individual UI components.

4. Build a reusable API client

Create src/lib/api.ts:

import { createFetch } from 'tanstack-fetch'

export interface User {
  id: string
  name: string
  email: string
}

export const api = createFetch({
  baseUrl: process.env.NEXT_PUBLIC_API_URL,
})

For browser-side requests, configure the public API URL in .env.local:

NEXT_PUBLIC_API_URL=https://api.example.com

The client is now the single place where you can configure common HTTP behavior.

For example, you can add authentication or status handlers later without changing every query function.

Why return data instead of an HTTP response?

With a traditional Axios request, you commonly write:

const response = await axios.get<User[]>('/users')

return response.data

With tanstack-fetch, the request can return the parsed data directly:

return api.get<User[]>('/users')

This matches what TanStack Query needs: a promise that resolves to the data or rejects with an error.

It's a small difference in code, but it removes repeated response-unwrapping logic from the API layer.

5. Connect the API client to TanStack Query

Now let's define our query outside the component.

Create src/queries/users.ts:

import { queryOptions } from '@tanstack/react-query'
import { api, type User } from '@/lib/api'

export const usersQueryOptions = queryOptions({
  queryKey: ['users'] as const,

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

  staleTime: 60_000,
})

Let's break this down.

queryKey identifies the data.

queryKey: ['users']

TanStack Query uses this key to cache and retrieve the user list.

queryFn defines how the data is fetched.

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

TanStack Query supplies the AbortSignal. Passing it to the HTTP client allows the request to be cancelled when appropriate.

staleTime controls data freshness.

staleTime: 60_000

The cached data is considered fresh for 60 seconds. This doesn't mean the data is deleted after a minute; it means TanStack Query can consider it stale and refetch according to its normal rules.

The benefit of extracting this definition is that both a client component and a server-side prefetch operation can reuse the same query options.

6. Render the users in a React component

Create src/app/users/users-client.tsx:

'use client'

import { useQuery } from '@tanstack/react-query'
import { usersQueryOptions } from '@/queries/users'

export function UsersClient() {
  const {
    data: users,
    isPending,
    isError,
    error,
  } = useQuery(usersQueryOptions)

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

  if (isError) {
    return <p>Failed to load users: {error.message}</p>
  }

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>
          <strong>{user.name}</strong>
          <span> — {user.email}</span>
        </li>
      ))}
    </ul>
  )
}

The component doesn't know how the API URL is configured, where authentication is handled, or how HTTP errors are constructed.

It only knows how to render the query state.

That is a useful separation of concerns: the component focuses on presentation, the query definition focuses on server state, and the HTTP client focuses on transport.

Don't forget the QueryClientProvider

TanStack Query needs a QueryClientProvider in the React component tree.

Create src/app/providers.tsx:

'use client'

import { useState } from 'react'
import {
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'

export function Providers({
  children,
}: {
  children: React.ReactNode
}) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 60_000,
          },
        },
      }),
  )

  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  )
}

Then register the provider in src/app/layout.tsx:

import { Providers } from './providers'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

Using a client-side provider this way creates a stable QueryClient for the browser application. For server-side prefetching, we'll create a separate QueryClient for each server render.

7. Handle mutations without duplicating API logic

Queries retrieve data. Mutations create or modify it.

Suppose we want to create a user.

'use client'

import {
  useMutation,
  useQueryClient,
} from '@tanstack/react-query'
import { api, type User } from '@/lib/api'

interface CreateUserInput {
  name: string
  email: string
}

export function CreateUserButton() {
  const queryClient = useQueryClient()

  const mutation = useMutation({
    mutationFn: (body: CreateUserInput) =>
      api.post<User, never, CreateUserInput>(
        '/users',
        { body },
      ),

    onSuccess: () =>
      queryClient.invalidateQueries({
        queryKey: ['users'],
      }),
  })

  return (
    <button
      disabled={mutation.isPending}
      onClick={() =>
        mutation.mutate({
          name: 'Ada Lovelace',
          email: 'ada@example.com',
        })
      }
    >
      {mutation.isPending ? 'Creating...' : 'Create user'}
    </button>
  )
}

The example assumes the endpoint returns the created user. If your API uses a different response format, adjust the response type accordingly.

The important part is that the mutation uses the same HTTP client as the query.

After a successful request, invalidateQueries marks the user list as stale so TanStack Query can refresh it when appropriate.

You don't need a new HTTP wrapper for POST requests, and you don't need to manually manage the cache yourself.

8. Handle HTTP errors properly

A production API needs more than a generic Request failed error.

Consider these common HTTP statuses:

Status	Meaning	Typical application behavior
400	Bad Request	Display validation or request feedback
401	Unauthorized	Handle the authentication flow
403	Forbidden	Display an access-denied state
404	Not Found	Display a missing-resource state
429	Too Many Requests	Respect rate limits and retry guidance
500	Internal Server Error	Display a recoverable failure state

tanstack-fetch provides a typed FetchError and status-specific handlers.

For example:

import {
  createFetch,
  isFetchError,
} from 'tanstack-fetch'

export const api = createFetch({
  baseUrl: process.env.NEXT_PUBLIC_API_URL,

  onUnauthorized: () => {
    // Trigger your application's authentication flow.
  },

  onForbidden: ({ status }) => {
    console.warn('Access denied:', status)
  },
})

The handlers are illustrative. Connect them to your application's actual authentication and notification mechanisms.

You can also narrow an error using isFetchError:

try {
  await api.get('/users')
} catch (error) {
  if (isFetchError(error)) {
    console.error({
      status: error.status,
      message: error.message,
    })
  }
}

This lets you distinguish an HTTP failure from unrelated JavaScript errors.

A security detail worth emphasizing: a 403 Forbidden response should not automatically trigger logout or token refresh. The user may be authenticated but lack permission to access a particular resource.

Keep authentication failures separate from authorization failures.

9. The Next.js challenge: server-side rendering

So far, we've built a client-side data-fetching flow.

Next.js adds another dimension: Server Components can fetch data before the browser renders the interactive UI.

You could use native fetch directly in a Server Component, and for simple cases that may be the best choice.

But what happens when you want to reuse your HTTP configuration, forward incoming cookies to an upstream API, and hydrate the same data into TanStack Query?

You need to think about the server and browser separately.

The server may need:

An absolute API URL.
Cookies from the incoming Next.js request.
A request-scoped query cache.
A dehydration step that transfers query state to the browser.

The browser, meanwhile, should not receive private environment variables or server-only authentication credentials.

Create a server-side API client

Create src/lib/api.server.ts:

import 'server-only'

import { cookies } from 'next/headers'
import { createFetch } from 'tanstack-fetch'

export async function createServerApi() {
  const cookieStore = await cookies()

  return createFetch({
    baseUrl: process.env.API_URL!,
    source: 'ssr',
    plugins: ['ssr-forward'],

    incoming: async () => ({
      cookie: cookieStore.toString(),
    }),
  })
}

Configure the server-only URL in .env.local:

API_URL=https://api.example.com

This is intentionally separate from NEXT_PUBLIC_API_URL.

The ssr-forward plugin forwards the relevant incoming cookie information during server-side requests. The source: 'ssr' setting identifies the server execution context.

The cookies() API is asynchronous in current Next.js versions, so we await it before creating the client.

Security note: Only forward headers your upstream API actually needs. Never expose session secrets through NEXT_PUBLIC_ environment variables, and never use a process-wide cache for user-specific authentication data.

10. Prefetch data on the server and hydrate it in the browser

Now we'll connect the server-side client to TanStack Query.

Create src/app/users/page.tsx:

import {
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from '@tanstack/react-query'

import { createServerApi } from '@/lib/api.server'
import { usersQueryOptions } from '@/queries/users'
import { UsersClient } from './users-client'

export default async function UsersPage() {
  const api = await createServerApi()
  const queryClient = new QueryClient()

  await queryClient.prefetchQuery({
    ...usersQueryOptions,
    queryFn: ({ signal }) =>
      api.get('/users', { signal }),
  })

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <UsersClient />
    </HydrationBoundary>
  )
}

This demonstrates the overall flow, but there is an important architectural detail.

The shared query options currently reference the browser-side API client. The server page overrides queryFn with the server-side client, so the prefetch uses the correct credentials and URL.

For a larger application, you can make this separation more explicit by defining a query-options factory that accepts the API client:

import { queryOptions } from '@tanstack/react-query'
import type { User } from '@/lib/api'

export function usersQueryOptionsFor(api: {
  get: <T>(path: string, options?: {
    signal?: AbortSignal
  }) => Promise<T>
}) {
  return queryOptions({
    queryKey: ['users'] as const,

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

    staleTime: 60_000,
  })
}

This is an illustrative interface; adapt it to the actual client type and generic signatures in your project.

With a shared factory, both the browser and server can use the same query definition while injecting their own correctly configured client.

What happens during hydration?

The sequence is:

Next.js renders the page on the server.
TanStack Query prefetches the user list.
dehydrate(queryClient) serializes the query cache into a transferable state.
HydrationBoundary restores that state in the React tree.
UsersClient reads the existing query rather than necessarily starting from an empty cache.

This avoids the common experience where the server renders one version of the page and the client immediately starts over with a fresh loading state.

For a complete production implementation, ensure that server and browser query keys and data types match. Create a fresh QueryClient for each server request, and verify that the API client used by the browser is configured independently from the server-only client.

For more detail, see the tanstack-fetch SSR guide and the TanStack Query SSR guide.

11. Why request cancellation matters

Let's return to the signal argument we used earlier.

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

Why bother passing it?

Imagine a search interface where the user types a query, changes the filters, or navigates away before the request finishes.

Without cancellation support, requests may continue even after their results are no longer useful.

TanStack Query provides an AbortSignal for query functions. Passing it through to the HTTP client allows the request to be cancelled when the query is cancelled.

This is especially valuable for:

Search-as-you-type interfaces.
Filterable data tables.
Rapid navigation between resource pages.
Expensive requests that are no longer needed.

The important principle is that cancellation should travel through the entire call chain. Supporting AbortSignal in a function is not enough if the HTTP client ignores it.

12. Do you actually need tanstack-fetch?

Let's be practical.

Next.js already provides native fetch, and it offers useful caching and request memoization behavior in the appropriate server-rendering contexts. TanStack Query also works with ordinary promise-based functions.

If your application has a few public API requests, adding another library may not improve anything.

tanstack-fetch becomes more useful when you want a consistent transport layer across multiple call sites or frameworks, typed HTTP errors, reusable status handlers, or authenticated SSE support.

Requirement	Possible approach
A simple request inside one Server Component	Native `fetch`
Client-side caching and background refetching	TanStack Query
Shared typed HTTP client for query functions	tanstack-fetch
Consistent status handling and typed HTTP errors	tanstack-fetch
Server-side cookie forwarding	tanstack-fetch with `ssr-forward`
Authenticated server-sent events	`tanstack-fetch/sse`

These tools aren't mutually exclusive. The right choice depends on your application's requirements.

The goal isn't to replace every native Next.js API. It's to avoid repeatedly solving the same transport problems in different places.

Final thoughts

A good API layer should make application code easier to understand, not introduce another abstraction for its own sake.

Start with a shared HTTP client. Define reusable query options. Pass the AbortSignal through. Use typed errors. When you introduce SSR, keep the server and browser authentication contexts separate and hydrate your query cache deliberately.

That's the architecture this combination makes possible:

React handles the interface.
TanStack Query manages server state.
tanstack-fetch handles HTTP transport.
Next.js provides the server-rendering and routing environment.

You don't need to implement every feature on day one. Start with one endpoint, validate the approach, and add the pieces that solve real problems in your application.

Explore the project

What does your current React API layer look like? Are you using native fetch, Axios, or a shared client with TanStack Query?

Building a Type-Safe API Layer with tanstack-fetch in Vue and Nuxt

Mohammad Garmabi — Mon, 26 Oct 2026 07:33:40 +0000

A practical guide to HTTP requests, TanStack Query, error handling, and server-side rendering

When building a Vue or Nuxt application, making an HTTP request is rarely the difficult part. The real challenge is keeping API calls consistent as the application grows.

You need to handle authentication, HTTP errors, request cancellation, loading states, caching, and server-side rendering. Before long, your project has multiple API utilities, duplicated interceptors, and slightly different error-handling logic across components.

Nuxt provides $fetch and useFetch, while Vue developers can also use Axios, ofetch, or the native Fetch API. These are all useful tools, but when your application uses TanStack Query, you may want a transport layer designed specifically for its query-function contract.

That's where tanstack-fetch comes in.

In this tutorial, we'll build a reusable API client for Vue 3 and Nuxt, connect it to TanStack Query, and explore when this approach makes sense.

1. Understanding the problem

Consider a typical API request using Axios:

const response = await axios.get<User[]>('/api/users')

return response.data

Axios returns a response object, so we need to extract response.data. We also need to ensure that HTTP errors are handled consistently and that requests can be cancelled when they are no longer needed.

Now consider a TanStack Query query function:

const { data } = useQuery({
  queryKey: ['users'],
  queryFn: async () => {
    const response = await axios.get<User[]>('/api/users')
    return response.data
  },
})

This works, but every query function may need to account for the HTTP client's response structure, error behavior, and cancellation mechanism.

As the project grows, the same concerns tend to appear in many places.

A better approach is to separate responsibilities:

HTTP client: Sends requests and handles transport-level behavior.
TanStack Query: Manages caching, retries, server state, and query lifecycle.
Vue or Nuxt: Renders the UI and manages application-level concerns.

The goal isn't to replace TanStack Query. It's to give it a cleaner HTTP client to work with.

2. What is tanstack-fetch?

tanstack-fetch is an open-source, TypeScript-first HTTP client created by Mohammad Garmabi. It is designed around the way TanStack Query expects query functions to behave.

It is an independent package, not an official TanStack project.

Its core contract is simple:

Return parsed data when a request succeeds.
Throw a typed FetchError when an HTTP request fails.
Honor AbortSignal so requests can be cancelled.
Keep authentication, interceptors, and other transport concerns in a reusable client.

For Vue and Nuxt, the package also provides optional integration helpers through tanstack-fetch/vue.

This means you can use the same underlying HTTP client without tying your API layer to a particular UI framework.

Documentation: https://mohamadgarmabi.github.io/tanstack-fetch/guide/vue

3. Installing the dependencies

For a Vue 3 application, install the client and Vue integration:

npm install tanstack-fetch vue

If you also want caching and server-state management with TanStack Query, install Vue Query:

npm install @tanstack/vue-query

For a Nuxt application, the client can be installed with:

npm install tanstack-fetch

Add @tanstack/vue-query if you plan to use TanStack Query.

One important distinction: tanstack-fetch and TanStack Query solve different problems. The first handles HTTP transport; the second manages server state.

4. Creating a reusable API client in Vue

Let's start with a simple Vue 3 application.

Instead of creating a new HTTP client inside every component, we'll create one shared instance.

Create src/lib/api.ts:

import { createFetch } from 'tanstack-fetch'

export interface User {
  id: string
  name: string
  email: string
}

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

Define the API URL in your .env file:

VITE_API_URL=https://api.example.com

Now the application has one place to configure its HTTP client.

You can add authentication, status handlers, and plugins as your requirements evolve, instead of distributing those concerns across individual requests.

Connecting the client to Vue

The Vue integration provides createFetchPlugin and a useFetch composable.

In src/main.ts:

import { createApp } from 'vue'
import { createFetchPlugin } from 'tanstack-fetch/vue'
import { api } from './lib/api'
import App from './App.vue'

createApp(App)
  .use(createFetchPlugin({ client: api }))
  .mount('#app')

The client is now available through the Vue integration.

Inside a component:

<script setup lang="ts">
import { useFetch } from 'tanstack-fetch/vue'

const api = useFetch()

const users = await api.get<User[]>('/users', {})
</script>

For applications that need shared request caching, however, we'll usually let TanStack Query manage the request lifecycle.

5. Integrating tanstack-fetch with TanStack Query

This is where the client becomes especially useful.

Install Vue Query if you haven't already:

npm install @tanstack/vue-query

import { createApp } from 'vue'
import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query'
import { createFetchPlugin } from 'tanstack-fetch/vue'
import { api } from './lib/api'
import App from './App.vue'

const queryClient = new QueryClient()

const app = createApp(App)

app.use(VueQueryPlugin, { queryClient })
app.use(createFetchPlugin({ client: api }))

app.mount('#app')

Now create a component that fetches users.

<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'
import { useFetch } from 'tanstack-fetch/vue'
import type { User } from '@/lib/api'

const api = useFetch()

const {
  data: users,
  error,
  isPending,
  isError,
} = useQuery({
  queryKey: ['users'],
  queryFn: ({ signal }) =>
    api.get<User[]>('/users', { signal }),
})
</script>

<template>
  <p v-if="isPending">Loading users...</p>

  <p v-else-if="isError">
    Failed to load users: {{ error.message }}
  </p>

  <ul v-else>
    <li v-for="user in users" :key="user.id">
      {{ user.name }} — {{ user.email }}
    </li>
  </ul>
</template>

Let's look at the important parts.

The query key

queryKey: ['users']

TanStack Query uses this key to identify and cache the query.

The query function

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

The HTTP client returns the parsed response data directly, so there is no need to unwrap an Axios response object.

Request cancellation

TanStack Query provides an AbortSignal to the query function. Passing it to api.get allows the HTTP request to participate in Query's cancellation lifecycle.

This matters when a query becomes obsolete or is cancelled during navigation or other application interactions.

Error handling

When the request fails with an HTTP error, tanstack-fetch throws a FetchError. TanStack Query can then expose the failure through its normal error state.

The result is a clear separation of responsibilities: the HTTP client handles the request, and TanStack Query manages the server state.

6. Using mutations to create data

The same approach works for POST requests.

Suppose we want to create a user and refresh the cached user list after a successful response.

<script setup lang="ts">
import {
  useMutation,
  useQueryClient,
} from '@tanstack/vue-query'
import { useFetch } from 'tanstack-fetch/vue'
import type { User } from '@/lib/api'

const api = useFetch()
const queryClient = useQueryClient()

interface CreateUserInput {
  name: string
  email: string
}

const createUser = useMutation({
  mutationFn: (body: CreateUserInput) =>
    api.post<User>('/users', { body }),

  onSuccess: () => {
    void queryClient.invalidateQueries({
      queryKey: ['users'],
    })
  },
})
</script>

<template>
  <button
    :disabled="createUser.isPending.value"
    @click="
      createUser.mutate({
        name: 'Ada Lovelace',
        email: 'ada@example.com',
      })
    "
  >
    Create user
  </button>

  <p v-if="createUser.isError.value">
    {{ createUser.error.value.message }}
  </p>
</template>

This example focuses on the API integration. In a production component, the input values would normally come from a form with validation.

The key idea is that mutations use the same API client as queries. You don't need a separate HTTP implementation for writes.

7. Setting up tanstack-fetch in Nuxt

Nuxt introduces another concern: the same application code may run on the server and in the browser.

Nuxt already provides $fetch and useFetch, so why introduce another client?

The answer depends on your architecture.

If you only need straightforward requests in Nuxt pages, the built-in tools may be sufficient. But if you want a shared HTTP client for TanStack Query, consistent typed HTTP errors, or features such as authenticated server-sent events, tanstack-fetch offers another option.

Let's register a shared client through a Nuxt plugin.

Create plugins/tanstack-fetch.ts:

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

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

  const api = createFetch({
    baseUrl: config.public.apiBase,
  })

  nuxtApp.vueApp.use(
    createFetchPlugin({ client: api }),
  )

  return {
    provide: {
      api,
    },
  }
})

Add the public API URL to nuxt.config.ts:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiBase: 'https://api.example.com',
    },
  },
})

The plugin registers the Vue integration and exposes the client through Nuxt's application context.

The example imports from tanstack-fetch/sse because that entry point also supports server-sent events. If you only need HTTP requests, use the core entry point instead:

import { createFetch } from 'tanstack-fetch'

Accessing the client in a Nuxt page

You can access the injected client through useNuxtApp():

<script setup lang="ts">
import type { User } from '@/lib/api'

const { $api } = useNuxtApp()

const users = await $api.get<User[]>('/users', {})
</script>

For a Nuxt application using TanStack Query, you can instead access the Vue composable:

<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'
import { useFetch as useFetchClient } from 'tanstack-fetch/vue'

interface User {
  id: string
  name: string
}

const api = useFetchClient()

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

<template>
  <p v-if="isPending">Loading...</p>

  <ul v-else>
    <li v-for="user in users" :key="user.id">
      {{ user.name }}
    </li>
  </ul>
</template>

Notice the alias:

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

Nuxt already has a composable named useFetch. Renaming the import avoids confusing Nuxt's built-in data-fetching composable with the tanstack-fetch client composable.

8. What about authentication and HTTP errors?

Real applications need more than successful GET requests.

Imagine an API that returns:

401 Unauthorized when the access token is invalid.
403 Forbidden when the current user lacks permission.
404 Not Found when a resource does not exist.
429 Too Many Requests when a rate limit is reached.
500 Internal Server Error when the server encounters a problem.

You can configure status handlers on the shared client rather than duplicating the same logic in every query function.

For example:

import { createFetch } from 'tanstack-fetch'

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

  onUnauthorized: () => {
    // Trigger your application's authentication flow.
  },

  onForbidden: ({ status }) => {
    console.warn('Access denied:', status)
  },

  onNotFound: ({ status }) => {
    console.warn('Resource not found:', status)
  },
})

These handlers are illustrative: connect them to your actual authentication and notification systems.

One security detail is important: a 403 response should not automatically be treated as an expired session. A user may be authenticated but lack permission to access a resource. Keep authorization failures distinct from authentication failures.

If your application uses refresh tokens, configure the appropriate refresh-token interceptor rather than implementing refresh logic independently in every component.

Also remember that a shared client does not replace server-side authorization. The backend must enforce permissions on every protected endpoint.

9. Server-side rendering and cookies in Nuxt

SSR is one of the most important architectural differences between Vue SPA development and Nuxt.

During server rendering, the browser's cookies are not automatically available to outgoing API requests. If the API relies on session cookies, your server-side client may need to forward the relevant incoming request headers.

tanstack-fetch provides an ssr-forward plugin for this use case.

The general setup involves:

Reading the relevant incoming request headers on the server.
Forwarding the required cookies or authorization headers to the upstream API.
Avoiding unnecessary forwarding in browser-side requests.
Ensuring that each server request uses the correct user's authentication context.

For example, the configuration can use the relevant plugin:

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

const api = createFetch({
  baseUrl: 'https://api.example.com',
  plugins: ['ssr-forward'],
})

Treat this as an illustration of the plugin entry point, not a complete Nuxt SSR configuration. Actual header forwarding must be wired to the incoming Nuxt request using the documented SSR integration.

See the official SSR guide for the Nuxt-specific setup.

Important: Never forward all incoming headers indiscriminately, expose private credentials through runtimeConfig.public, or store user-specific authentication state in a process-wide singleton. Incorrect SSR authentication can leak data between users.

For a complete Nuxt application, configure Vue Query's server-side prefetching and hydration separately as well. Registering an HTTP client alone does not automatically dehydrate and hydrate the query cache.

10. When should you use tanstack-fetch instead of `$fetch`?

Nuxt's built-in $fetch is a good choice for server routes, simple API calls, and applications that don't need a separate transport layer.

tanstack-fetch becomes more interesting when your application needs a consistent HTTP contract across several parts of the stack.

Requirement	Practical choice
Simple request in a Nuxt server route	`$fetch`
Nuxt page data without TanStack Query	`useFetch` or `$fetch`
TanStack Query with a shared typed HTTP client	tanstack-fetch
Consistent HTTP errors and status handlers	tanstack-fetch
Shared transport configuration across Vue and other frameworks	tanstack-fetch
Authenticated SSE with reconnection support	tanstack-fetch SSE integration

The important point isn't that one client is universally better. Each solves a slightly different problem.

If your project is small and $fetch already meets your requirements, adding another abstraction may not be worthwhile.

If your project relies heavily on TanStack Query and needs consistent authentication, error handling, cancellation, and transport configuration, a dedicated client can reduce repeated glue code.

11. Final thoughts

A maintainable frontend architecture doesn't require the largest possible set of abstractions. It requires clear boundaries between responsibilities.

TanStack Query should manage server state. Vue and Nuxt should handle rendering and framework-specific behavior. The HTTP client should provide a predictable interface for communicating with the backend.

tanstack-fetch is designed to connect those layers with a small, typed API that works with Vue 3 and Nuxt.

Start with a single shared client, connect it to your queries, and add authentication, SSR forwarding, or SSE only when your application needs them.

You can explore the package, examples, and framework integrations here:

Documentation: https://mohamadgarmabi.github.io/tanstack-fetch/
Vue & Nuxt guide: https://mohamadgarmabi.github.io/tanstack-fetch/guide/vue
TanStack Query integration: https://mohamadgarmabi.github.io/tanstack-fetch/guide/tanstack-query
GitHub: https://github.com/mohamadgarmabi/tanstack-fetch

The objective is straightforward: fewer duplicated transport concerns, predictable errors, and a cleaner boundary between HTTP requests and server-state management.

DEV Community: Mohammad Garmabi

tanstack-fetch 2.2.1: I audited every entry point and fixed 31 bugs

1. A relative baseUrl actually works now

2. Retries no longer re-send your POST by accident

3. SSE resume does what its name says

4. SSR leaks in Vue/Nuxt and Svelte

5. A DevTools XSS

6. Codemods that produce working code

Behaviour changes to check

Cost

Known limits

Mock Your API Inside the Client: HTTP, SSE, NDJSON & WebSocket with tanstack-fetch

Step 1 — One client, one switch

Step 2 — A REST endpoint

Step 3 — A live SSE feed

Step 4 — A streaming NDJSON response

Step 5 — A WebSocket room

Step 6 — Errors and latency

Step 7 — Switch to the real API, one route at a time

Bonus: keep fixtures out of production

Bonus: reuse the same mocks in tests

Cheat sheet

Links

TanStack Start + tanstack-fetch: 6 data fetching patterns

I'm the creator of tanstack-fetch, an HTTP client designed to work with TanStack Query's server-state model. It is an independent community package, not an official TanStack project.

1. Start with the right mental model

2. Pattern one: Fetch data directly

3. Pattern two: Share route loaders and Query cache

4. Pattern three: Handle SSR and authenticated requests

5. Pattern four: Mutations and cache invalidation

6. Pattern five: Centralize HTTP errors and authentication behavior

7. Pattern six: Combine REST queries with live SSE updates

8. What about Server Functions?

9. A practical project structure

10. How should you choose?

Final thoughts

React axios vs tanstack-fetch for TanStack Query

TL;DR

Mental model

Side-by-side

axios + Query (glue)

tanstack-fetch + Query (native)

Bootstrap / wiring

Comparison graph: where glue accumulates

Feature matrix

Auth, status handlers, refresh

Mutations

Live data: SSE

tRPC over the same client

Migrate

Suggested folder layout

Decision tree

Checklist

Try it

Related

Series

tanstack-fetch 2.1.0: abortable retries, safer token refresh

Upgrade

Fixed

Cancelling during a retry delay

Colons inside a path segment

Refresh token: no second refresh on a late 401

Stream bodies are never retried

Added

Array query values

parseAs: 'arrayBuffer' | 'stream'

tanstack-fetch/full

Correct types for CommonJS

Bundle size

Good to know

Stop adapting axios to TanStack Query: a fetch client built for queryFn

The usual glue

The same thing with tanstack-fetch

Typed errors in the UI

Only pay for what you use

SSE with auth

Migrating

Links

Your SSE Connection Dropped. Now What? Building Resumable Server-Sent Events in JavaScript

1. Understanding the problem

1. A relative `baseUrl` actually works now

`parseAs: 'arrayBuffer' | 'stream'`

`tanstack-fetch/full`

3. Understanding `Last-Event-ID`

Why use `createFetch`?

Why use `createTRPCFetchClient`?

Why use `createTRPCOptionsProxy`?

`ensureQueryData` in the loader

`useQuery` in the component

6. What happens when the user navigates to `/posts`?