DEV Community: Mohammad Garmabi

I Redesigned the tanstack-fetch Website ✨

Mohammad Garmabi — Wed, 21 Oct 2026 08:15:27 +0000

A small update to my open-source project!

I've redesigned the tanstack-fetch website with a focus on a cleaner presentation and a better documentation experience.

The idea behind tanstack-fetch remains the same: a type-safe HTTP client that works naturally alongside TanStack Query, without mixing HTTP transport logic with server-state management.

Check out the new look 👇

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

I'd love to hear what you think. If you're working with TypeScript, Fetch, or TanStack Query, your feedback is especially valuable.

tanstack-fetch 1.7.1 Is Out: Timeouts, URL Params, Binary Bodies, and HTTP Errors

Mohammad Garmabi — Sun, 18 Oct 2026 07:46:11 +0000

I've released tanstack-fetch 1.7.1, a bug-fix release focused on the core HTTP request path.

No new APIs in this version—just fixes for edge cases that can cause confusing behavior in real applications.

npm install tanstack-fetch@1.7.1

What's Changed?

1. URL parameters are matched more precisely

Colons in URLs such as http://localhost:8080 and query values such as ?t=10:30 are no longer mistaken for path parameters. Only the pathname is scanned for :id and {id} placeholders.

2. Timeouts are recognized as aborts

A timeout now rejects with TimeoutError, and isAbortError() recognizes it. This separates timeouts from ordinary network failures and cancellations.

3. Timeout timers are cleaned up

Timers are cleared when request attempts finish and unreferenced in Node.js, avoiding unnecessary process-lifetime extension in SSR and serverless environments.

4. Binary and stream request bodies work as intended

Typed arrays, DataView, and ReadableStream are sent in their intended formats rather than being JSON-encoded. Node stream requests set duplex: 'half'.

5. HTTP errors keep their real status

A gateway response such as 502 with an HTML body no longer gets reduced to a parsing error. The error preserves status, uses HTTP_ERROR, exposes raw text as error.body, and runs onResponseError interceptors.

try {
  await api.get('/gateway')
} catch (error) {
  if (isFetchError(error)) {
    console.log(error.status) // 502
    console.log(error.code)   // 'HTTP_ERROR'
    console.log(error.body)   // raw gateway response
  }
}

One Migration Detail

If your code detects timeouts with error.code === 'NETWORK_ERROR', update it to use isAbortError(error) and check for TimeoutError when needed.

Timeout failures no longer pass through onRequestError interceptors, so review custom retry logic that depends on those interceptors. You can handle TimeoutError at the call site or use TanStack Query's retry behavior.

Try It

npm install tanstack-fetch@1.7.1

Full release notes:

https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-1-7-1

tanstack-fetch is an independent project, not an official TanStack package. Feedback and bug reports are welcome.

— Mohammad Garmabi

Building Production-Ready React Data Flows with tanstack-fetch and TanStack Query

Mohammad Garmabi — Sat, 17 Oct 2026 06:26:20 +0000

TanStack Query is excellent at managing server state. It handles caching, background refetching, invalidation, retries, mutations, and synchronization between components.

But managing server state and communicating with an API are two different responsibilities.

In a real application, you also need to handle:

Expired access tokens and automatic refresh.
Multiple requests failing with 401 at the same time.
Different HTTP errors, from 400 and 403 to 429 and 500.
Typed request parameters, payloads, and responses.
Request cancellation and cache synchronization.
Live updates through Server-Sent Events (SSE).

This is where tanstack-fetch and TanStack Query work together.

tanstack-fetch handles HTTP transport, authentication, typed errors, interceptors, and streaming.
TanStack Query manages server state, caching, mutations, and synchronization.
TypeScript and Zod help define and validate application contracts.

Let's build three realistic features for a financial operations dashboard: authentication with automatic token refresh, reliable API error handling, and type-safe order management.

1. Install the dependencies

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

We'll use React with TypeScript and a Vite application. The examples use an API that returns JSON and an authentication system that provides a short-lived access token and an HTTP-only refresh cookie.

2. Create a shared API client

Instead of implementing authentication headers and error handling in every feature, create a single HTTP client.

// src/lib/api.ts
import { createFetch } from 'tanstack-fetch'

export const api = createFetch({
  baseUrl: import.meta.env.VITE_API_URL,
  credentials: 'include',
  getToken: () => localStorage.getItem('access_token'),
})

This is enough for a basic application. However, a production application needs a consistent strategy for handling expired tokens and HTTP errors.

We'll extend this client in the next section.

One important design principle: the HTTP client should not know about React Query's cache, query keys, or components. It should handle HTTP concerns and return data or throw a meaningful error.

3. Scenario one: Automatic token refresh

Imagine that a user opens an account dashboard. Several requests run in parallel:

GET /accounts
GET /transactions
GET /profile
GET /notifications

The access token expires just before these requests reach the API.

All four requests receive 401 Unauthorized.

A naive implementation might start four refresh requests. Other implementations retry requests indefinitely or accidentally refresh when the server returns 403 Forbidden.

We want a different result:

Detect an expired access token.
Start one refresh operation.
Make concurrent requests wait for that operation.
Store the new access token.
Retry each eligible original request once.
Redirect to login if refreshing fails.

Implement the refresh-token interceptor

tanstack-fetch provides createRefreshTokenInterceptor from tanstack-fetch/plugins.

// src/lib/api.ts
import { createFetch } from 'tanstack-fetch'
import {
  createRefreshTokenInterceptor,
} from 'tanstack-fetch/plugins'

type RefreshResponse = {
  accessToken: string
  expiresIn: number
}

let accessToken: string | null =
  localStorage.getItem('access_token')

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

function persistToken(
  token: string,
  expiresInSeconds: number,
) {
  accessToken = token
  expiresAt = Date.now() + expiresInSeconds * 1000

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

function clearSession() {
  accessToken = null
  expiresAt = 0

  localStorage.removeItem('access_token')
  localStorage.removeItem('access_expires_at')

  if (window.location.pathname !== '/login') {
    window.location.assign('/login')
  }
}

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

  getToken: () => accessToken,

  onUnauthorized: clearSession,
})

api.use(
  'refresh-token',
  createRefreshTokenInterceptor({
    refresh: async () => {
      const result = await api.post<RefreshResponse>(
        '/auth/refresh',
        {
          interceptors: {
            eject: ['refresh-token', 'auth'],
          },
        },
      )

      persistToken(
        result.accessToken,
        result.expiresIn,
      )
    },

    // Refresh before the token expires.
    before: {
      getExpiresAt: () => expiresAt,
      skewMs: 60_000,
    },

    // Also recover from an unexpected 401.
    after: {
      enabled: true,
    },
  }),
)

This example assumes that /auth/refresh accepts the refresh cookie and returns an access token with its lifetime. Adapt the response type to your backend's actual contract.

The interceptor's before strategy refreshes the token one minute before expiration. Its after strategy handles an unexpected 401 by refreshing and retrying the original request.

The refresh request explicitly ejects the refresh-token and auth interceptors. This prevents the refresh request from recursively triggering its own refresh flow. The plugin also coordinates concurrent refresh operations through a shared in-flight promise.

See the refresh-token recipe for the complete documented configuration.

Why does this matter?

Consider five concurrent queries that receive 401.

Without coordinated refresh, each query may independently call /auth/refresh. Depending on the backend, this can invalidate rotating refresh tokens, create race conditions, or cause unnecessary load.

With the interceptor, eligible requests share one refresh operation instead of implementing their own token-refresh queues.

Also note that this example is browser-specific. In Next.js or another SSR environment, don't access localStorage or window during server initialization. Use a request-scoped authentication strategy and the appropriate cookie-forwarding configuration instead.

`401` is not `403`

These responses mean different things:

Status	Meaning	Expected behavior
`401`	Authentication is missing or invalid	Attempt the configured refresh flow
`403`	The user lacks permission	Show an authorization error
`404`	Resource not found	Show a not-found state
`429`	Rate limit exceeded	Apply an appropriate backoff
`500`	Server failure	Show a recoverable error when appropriate

A 403 should not automatically trigger token refresh or logout. Refresh is an authentication recovery mechanism, not a general response to every failed request.

4. Scenario two: Handle HTTP errors properly

Now let's build an API layer that handles different failures consistently.

A common problem with ordinary fetch is that receiving a 404 or 500 does not automatically reject the promise. The application must inspect the response and throw its own error.

tanstack-fetch is designed to return successful response data and throw a typed FetchError for HTTP failures. It also provides isFetchError for narrowing errors safely.

Configure status-specific behavior

Extend the client configuration with handlers for important HTTP statuses:

// src/lib/api.ts
import {
  createFetch,
  parseRetryAfter,
} from 'tanstack-fetch'

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

  getToken: () => accessToken,

  onUnauthorized: clearSession,

  onForbidden: () => {
    console.warn('The user lacks permission.')
  },

  onNotFound: () => {
    console.warn('The requested resource was not found.')
  },

  onTooManyRequests: ({ context }) => ({
    action: 'retry',
    delayMs: parseRetryAfter(
      context.response?.headers,
      2_000,
    ),
  }),

  onServerError: ({ status }) => {
    console.error(`API server error: ${status}`)
  },
})

The example illustrates the status-handler API. In the final client, retain the credentials and refresh-token interceptor configuration from the previous section rather than creating a separate client.

The 429 handler uses Retry-After when available and a two-second fallback otherwise. Retry only when the operation is safe to repeat and the backend's rate-limit policy permits it.

For a 500, logging is useful, but logging alone is not a user-facing error strategy. The component should still show a suitable fallback state.

Display typed errors in React

Let's create a reusable error message component.

// src/components/ApiError.tsx
import {
  isFetchError,
} from 'tanstack-fetch'

type Props = {
  error: Error | null
}

export function ApiError({ error }: Props) {
  if (!error) return null

  if (isFetchError(error)) {
    switch (error.status) {
      case 400:
        return <p>Invalid request.</p>

      case 401:
        return <p>Your session has expired.</p>

      case 403:
        return <p>You do not have permission.</p>

      case 404:
        return <p>The requested resource was not found.</p>

      case 429:
        return <p>Too many requests. Please try again.</p>

      default:
        if (error.status >= 500) {
          return <p>The server is temporarily unavailable.</p>
        }
    }
  }

  return <p>Something went wrong. Please try again.</p>
}

This example uses the documented isFetchError type guard and status field. It deliberately avoids displaying raw server error bodies to users, because those bodies may contain internal details.

The benefit is that components can distinguish HTTP failures without duplicating low-level response parsing.

5. Connect the API client to TanStack Query

With the transport layer in place, the query function stays simple.

Let's fetch an account balance.

// src/features/accounts/accounts.api.ts
import { api } from '@/lib/api'

export interface Account {
  id: string
  balance: number
  currency: string
}

export function getAccount(accountId: string) {
  return api.get<Account>(
    `/accounts/${accountId}`,
  )
}

Define a reusable query option:

// src/features/accounts/accounts.queries.ts
import { queryOptions } from '@tanstack/react-query'
import { getAccount } from './accounts.api'

export const accountQuery = (accountId: string) =>
  queryOptions({
    queryKey: ['accounts', accountId],

    queryFn: ({ signal }) =>
      getAccount(accountId, { signal }),

    staleTime: 30_000,

    retry: (failureCount, error) => {
      if (
        error instanceof Error &&
        'status' in error &&
        typeof error.status === 'number' &&
        error.status >= 400 &&
        error.status < 500
      ) {
        return false
      }

      return failureCount < 2
    },
  })

Here, the AbortSignal is passed to the HTTP request so that TanStack Query can cancel obsolete work. The retry policy avoids retrying ordinary client errors; refine it to match your API and authentication strategy.

In particular, authentication recovery belongs to the HTTP layer. Query retries should not create a second, competing refresh-token mechanism.

Use the query in a component:

import { useQuery } from '@tanstack/react-query'
import { accountQuery } from './accounts.queries'
import { ApiError } from '@/components/ApiError'

export function AccountBalance({
  accountId,
}: {
  accountId: string
}) {
  const { data, isPending, error } = useQuery(
    accountQuery(accountId),
  )

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

  if (error) {
    return <ApiError error={error} />
  }

  return (
    <p>
      {data.balance.toLocaleString()} {data.currency}
    </p>
  )
}

The query function doesn't need to know how tokens are refreshed or how HTTP responses are parsed. It calls the API function, and TanStack Query handles the server-state lifecycle.

6. Scenario three: Type-safe order management

Consider an operations dashboard where an employee reviews orders, filters them by status, and approves or rejects individual orders.

Define the domain contract first.

// src/features/orders/orders.types.ts
export type OrderStatus =
  | 'pending'
  | 'approved'
  | 'rejected'

export interface Order {
  id: string
  status: OrderStatus
  amount: number
}

export interface UpdateOrderInput {
  status: 'approved' | 'rejected'
  reason?: string
}

Fetch an order

// src/features/orders/orders.api.ts
import { api } from '@/lib/api'
import type {
  Order,
  UpdateOrderInput,
} from './orders.types'

export function getOrder(orderId: string) {
  return api.get<Order>(
    `/orders/${orderId}`,
  )
}

export function updateOrder(
  orderId: string,
  input: UpdateOrderInput,
) {
  return api.patch<Order>(
    `/orders/${orderId}`,
    { body: input },
  )
}

These generic response types provide compile-time expectations. They do not validate the server's JSON at runtime, so validate untrusted responses at the API boundary if the application requires stronger guarantees.

Define the query

// src/features/orders/orders.queries.ts
import { queryOptions } from '@tanstack/react-query'
import { getOrder } from './orders.api'

export const orderQuery = (orderId: string) =>
  queryOptions({
    queryKey: ['orders', orderId],
    queryFn: ({ signal }) =>
      getOrder(orderId, { signal }),
  })

The order ID is part of the query key because each order represents a distinct cached resource.

Update an order with a mutation

// src/features/orders/orders.mutations.ts
import {
  useMutation,
  useQueryClient,
} from '@tanstack/react-query'

import { updateOrder } from './orders.api'
import type {
  UpdateOrderInput,
} from './orders.types'

export function useUpdateOrder(orderId: string) {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (input: UpdateOrderInput) =>
      updateOrder(orderId, input),

    onSuccess: (updatedOrder) => {
      queryClient.setQueryData(
        ['orders', orderId],
        updatedOrder,
      )

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

Use it in an order review component:

const mutation = useUpdateOrder(orderId)

function approveOrder() {
  mutation.mutate({
    status: 'approved',
  })
}

After a successful mutation, the individual order is updated immediately in the cache, and related order queries are invalidated.

The important separation remains unchanged: tanstack-fetch sends the request and returns typed data; TanStack Query synchronizes that data across the application.

7. Where does SSE fit?

Some dashboards need live transaction updates rather than periodic polling.

For example, a transaction might move from pending to completed while the user is looking at the page.

The initial transaction list belongs in TanStack Query. The SSE connection delivers subsequent changes.

With tanstack-fetch, authenticated SSE is available through the separate tanstack-fetch/sse entry point. Unlike native EventSource, a fetch-based SSE transport can use ordinary HTTP authorization headers.

A typical architecture looks like this:

Initial request
      |
      v
tanstack-fetch
      |
      v
TanStack Query cache
      |
      v
React components

SSE connection
      |
      v
Transaction event
      |
      v
Update or invalidate Query cache
      |
      v
React components

For each incoming event, either update the relevant cached transaction with queryClient.setQueryData or invalidate the affected query when the event does not contain enough information to safely update the cached representation.

Keep the stream's lifecycle separate from the query function. A query fetches a snapshot; an SSE subscription delivers ongoing events.

8. The responsibility matrix

Concern	Appropriate layer
HTTP requests and base URL	`tanstack-fetch`
Access-token attachment	HTTP client
Refresh and retry after `401`	Refresh-token interceptor
`403`, `404`, `429`, and `5xx` handling	HTTP status handlers and UI
Cache and background refetching	TanStack Query
Mutation lifecycle and invalidation	TanStack Query
Request cancellation	TanStack Query + `AbortSignal`
TypeScript API contracts	TypeScript
Runtime payload validation	Zod or equivalent
Live event delivery	SSE transport
Synchronizing live data	TanStack Query cache

Final thoughts

A production-ready data layer needs more than a convenient way to send a GET request.

It needs a clear boundary between HTTP transport and server-state management, predictable error semantics, coordinated authentication recovery, and explicit cache synchronization.

tanstack-fetch provides the HTTP-side building blocks, including typed FetchError handling and a refresh-token interceptor designed to handle concurrent refreshes. TanStack Query remains responsible for the lifecycle of server state.

The result is less duplicated request logic and a more consistent architecture as the application grows.

References

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

TanStack Start 1.0 + tanstack-fetch: 6 Real-World Data Fetching Patterns

Mohammad Garmabi — Wed, 14 Oct 2026 11:18:43 +0000

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.

Install the core dependencies:

npm install tanstack-fetch @tanstack/react-query

Follow the current TanStack Start and Router documentation for the framework-specific setup and SSR integration:

2. Pattern one: Fetch data directly

Not every request needs a complicated abstraction.

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

// src/lib/api.ts
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.

Both approaches can be valid, but they introduce extra synchronization work when the same resource is used across routes or components.

Instead, define reusable query options:

// src/queries/users.ts
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.

This does not mean a network request can never happen again. A stale query, invalidation, or an explicit refetch can legitimately trigger one. The goal is to avoid unnecessary duplicate fetching and separate caches.

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.

A server-aware client can be configured like this:

// Illustrative server-side setup
import { createFetch } from 'tanstack-fetch'

export const createServerApi = (
  apiOrigin: string,
  cookie: string | undefined,
) =>
  createFetch({
    baseUrl: `${apiOrigin}/api`,
    source: 'ssr',
    plugins: ['ssr-forward'],
    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.

A server-side request may also need to preserve an authorization header or request ID. Those should be forwarded deliberately rather than copying every incoming header.

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.

Do not redirect to login on every error. In particular, a 403 should not automatically trigger logout, and a 404 should not be treated as an expired session.

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.

For authenticated streams, verify how credentials are transported. The browser's native EventSource API does not provide a general option for setting arbitrary authorization headers; a fetch-based SSE client can be useful when those headers are required.

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?

TanStack Start + TanStack Query: Sharing Data Between Loaders and Components

Mohammad Garmabi — Tue, 13 Oct 2026 06:25:26 +0000

TanStack Start + TanStack Query: Sharing Data Between Loaders and Components

One thing I like about TanStack Start is how naturally TanStack Router and TanStack Query fit together.

A route loader can fetch data before rendering. A component can read that data through useQuery. With shared query options, both can use the same cache instead of maintaining separate data-fetching logic.

But there is another piece to consider: the HTTP client.

How do you handle typed responses, authentication, request cancellation, SSR headers, and errors without duplicating the same logic across loaders and components?

That's where I use tanstack-fetch, an independent HTTP client designed to work with the TanStack Query mental model.

In this guide, we'll connect TanStack Router, TanStack Query, and tanstack-fetch, then look at SSR, mutations, SSE, tRPC, and migration.

The core idea

Keep three responsibilities separate:

TanStack Router: navigation and route-level loading.
TanStack Query: server-state caching, synchronization, and invalidation.
tanstack-fetch: HTTP requests, typed responses, errors, and request-level behavior.

The goal is simple: don't create one fetching strategy for loaders and another for components.

1. Install the dependencies

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

2. Define reusable query options

Start by defining the query once. Both the loader and the component can reuse it.

// queries/users.ts
import { queryOptions } from '@tanstack/react-query'
import { api } from '~/lib/api'

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

Notice the signal parameter.

TanStack Query provides an AbortSignal to the query function. Passing it to the HTTP client allows the request to be cancelled when appropriate.

This is one small detail that is easy to miss when implementing data fetching manually.

3. Put QueryClient in router context

The router needs access to the same QueryClient used by your React application.

// router.tsx
import {
  createRouter,
} from '@tanstack/react-router'
import {
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'

export const queryClient = new QueryClient()

export const router = createRouter({
  routeTree,
  context: {
    queryClient,
  },
  Wrap: ({ children }) => (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  ),
})

This illustrates the wiring. In a production TanStack Start application, follow the framework's SSR setup and create request-scoped server state where required rather than sharing a mutable server-side QueryClient between users.

4. Load data before rendering

Now the route loader can populate the Query cache.

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

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

  component: UsersPage,
})

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

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

The loader and component share the same query definition.

ensureQueryData ensures that cached data is available, fetching it when the query has no cached result. If you also need to revalidate stale data before continuing, consider ensureQueryData with revalidateIfStale or an appropriate prefetch strategy, depending on your desired navigation behavior.

This gives you a clear separation of responsibilities: the router coordinates loading, Query owns the cache, and the component subscribes to it.

5. Configure the HTTP client for SSR

Server-side rendering introduces another concern: requests may need headers or cookies from the incoming request.

Here's a simplified client configuration:

// lib/api.ts
import { createFetch } from 'tanstack-fetch'

export const api = createFetch({
  baseUrl:
    typeof window === 'undefined'
      ? `${process.env.SSR_ORIGIN ?? ''}/api`
      : '/api',

  source:
    typeof window === 'undefined'
      ? 'ssr'
      : 'browser',

  plugins:
    typeof window === 'undefined'
      ? ['ssr-forward']
      : [],
})

This is an illustrative configuration. Verify the ssr-forward plugin's setup against your version of tanstack-fetch and the headers available in your server request context. Forward only the headers your application needs.

For nested routes, the same pattern applies:

userQueryOptions(params.userId)

Use the resulting options in both the loader and the component. When routes have dependent data requirements, use route-level prefetching and carefully designed query dependencies to avoid unnecessary waterfalls.

6. Handle mutations with the same cache

Mutations should invalidate the same Query cache that loaders and components use.

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

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

After a successful mutation, Query can refetch the affected data according to its invalidation and observer behavior.

You don't need a separate cache invalidation mechanism just because the initial request happened in a route loader.

7. Authentication and token refresh

Authentication is another place where HTTP logic tends to get duplicated.

An HTTP client can centralize token retrieval and refresh behavior rather than implementing it separately in every query function.

For example, tanstack-fetch provides a refresh-token interceptor:

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

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

api.use(
  'refresh-token',
  createRefreshTokenInterceptor({
    refresh: async () => {
      // Refresh the access token using your
      // application's refresh endpoint.
    },
  }),
)

The refresh implementation depends on your authentication flow and the installed package version. Configure the interceptor using the documented options for your version.

For production applications, consider concurrent refreshes, retry limits, refresh-token rotation, and what should happen when refreshing fails. Avoid using localStorage for credentials if your security model requires an HttpOnly cookie-based session.

The benefit of centralizing this behavior is that individual query functions can focus on retrieving data instead of repeating authentication logic.

8. Add live updates with Server-Sent Events

Not every screen is a good fit for request-and-response fetching.

Dashboards, notifications, and live status pages may need server-pushed updates. Browser EventSource does not support arbitrary Authorization headers, which can complicate authenticated SSE connections.

The tanstack-fetch/sse entry point provides a fetch-based alternative.

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

Use the documented useSse API in a client-side route component for the stream, while keeping initial data loading in your normal Query-based loader.

A practical division is:

Load the initial state through a REST or tRPC query.
Subscribe to updates through SSE.
Update the relevant Query cache or invalidate queries when events arrive.
Close the stream when the component no longer needs it.

A reconnect alone doesn't guarantee that no events were missed. If your application needs reliable resumption, design the server protocol around event IDs, replay, and recovery.

9. What about tRPC?

If your application already uses tRPC, you don't necessarily need a separate HTTP transport strategy for every feature.

TanStack Start has established integration patterns using createTRPCOptionsProxy and router context.

See the tanstack-fetch TanStack Start tRPC guide for the integration details.

The important architectural principle remains the same: keep transport concerns separate from query caching and route orchestration.

10. What does tanstack-fetch actually simplify?

The benefit isn't that raw fetch is bad. For a small application with a few requests, it may be all you need.

The difference becomes more relevant as an application grows.

Concern	Raw `fetch`	tanstack-fetch
HTTP requests	Built in	Built-in
Typed application responses	Define your own conventions	Typed client API
HTTP error handling	Implement your own checks	`FetchError`-based handling
Query cancellation	Pass the signal manually	Integrate through the query function
Token refresh	Implement your own flow	Refresh interceptor available
SSE	Build your own integration	Dedicated SSE entry point
Router and Query integration	Compose the pieces yourself	Reuse the same client in query options

These are architectural trade-offs, not benchmark results. Your application's actual complexity will depend on the features you need and how consistently your existing code handles them.

11. Migrate incrementally

You don't have to rewrite every request to adopt this approach.

Start with one route that currently fetches data in its loader.

Move the request into a reusable queryOptions definition.
Replace the loader request with ensureQueryData.
Read the same query through useQuery.
Pass Query's signal to the HTTP request.
Move repeated HTTP behavior into your client configuration.

You can also explore the migration CLI:

npx tanstack-fetch migrate \
  --from fetch \
  --framework react \
  --write

npx tanstack-fetch doctor --dir ./src

Review generated changes before committing them, especially around authentication, error handling, and SSR behavior.

12. Suggested project structure

A simple structure can keep the boundaries clear:

src/
  lib/
    api.ts
  queries/
    users.ts
  router.tsx
  routes/
    users.tsx
    users.$id.tsx

You can introduce additional modules for authentication, mutations, and live subscriptions as the application grows. There's no need to add abstractions before the codebase needs them.

Final thoughts

TanStack Start, TanStack Router, and TanStack Query already provide a strong foundation for server-rendered React applications.

The pattern I find most useful is to let each layer do one job:

Router coordinates when route data is needed.
Query manages cached server state.
The HTTP client centralizes transport behavior.

tanstack-fetch is an independent open-source project built around that approach. It isn't an official TanStack package, and you don't need it to use TanStack Start. It is an option worth evaluating when typed HTTP requests, shared transport behavior, authentication, or SSE become recurring concerns in your application.

Explore the documentation: tanstack-fetch.

If you're using TanStack Start in production, I'd be interested to hear how you handle request-scoped Query clients, SSR authentication, and cache reuse between loaders and components.

Angular API Requests with tanstack-fetch and TanStack Query

Mohammad Garmabi — Mon, 12 Oct 2026 06:29:33 +0000

Angular API Requests with tanstack-fetch and TanStack Query

How do you keep HTTP requests consistent across an Angular application without mixing API transport, server-state management, and UI logic?

One practical option is to use a dedicated HTTP client alongside TanStack Query.

In this tutorial, we'll build a small Angular users screen using tanstack-fetch.

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

Install

npm install tanstack-fetch
npm install @tanstack/angular-query-experimental

Create the client

// api.ts
import { createFetch } from 'tanstack-fetch';

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

export const api = createFetch({
  baseUrl: 'https://jsonplaceholder.typicode.com',
});

Provide it through Angular DI

import { bootstrapApplication } from '@angular/platform-browser';
import { provideFetchClient } from 'tanstack-fetch/angular';

import { api } from './api';
import { UsersComponent } from './users.component';

bootstrapApplication(UsersComponent, {
  providers: [
    provideFetchClient({ client: api }),
  ],
});

Query data and pass AbortSignal

import { Component } from '@angular/core';
import { injectQuery } from '@tanstack/angular-query-experimental';
import { injectFetch } from 'tanstack-fetch/angular';
import { isFetchError } from 'tanstack-fetch';

import { User } from './api';

@Component({
  selector: 'app-users',
  standalone: true,
  template: `
    @if (users.isPending()) {
      <p>Loading...</p>
    } @else if (users.isError()) {
      <p>{{ errorLabel() }}</p>
    } @else {
      @for (user of users.data(); track user.id) {
        <p>{{ user.name }}</p>
      }
    }
  `,
})
export class UsersComponent {
  private readonly api = injectFetch();

  readonly users = injectQuery(() => ({
    queryKey: ['users'],
    queryFn: ({ signal }: { signal: AbortSignal }) =>
      this.api.get<User[]>('/users', { signal }),
  }));

  errorLabel(): string {
    const error = this.users.error();

    return isFetchError(error)
      ? `HTTP ${error.status}: ${error.message}`
      : 'Request failed';
  }
}

What's happening here?

There are three distinct responsibilities:

Angular DI provides the configured HTTP client.
tanstack-fetch handles the HTTP request and typed response.
TanStack Query manages query state and caching.

Passing signal matters. A query can be cancelled as its lifecycle changes, and forwarding the AbortSignal lets the HTTP request participate in that cancellation.

Error handling is also explicit: isFetchError() identifies errors produced by the HTTP client, allowing the UI to display an HTTP status where available.

What about authentication and retries?

Treat these as separate design decisions. Configure authentication, retry behavior, and application-specific error policies according to your security and reliability requirements. Don't assume every HTTP error should be retried, and don't automatically treat every authorization response as a reason to log a user out.

When is this useful?

Consider this architecture when your Angular app has multiple API endpoints, shared HTTP configuration, typed data contracts, and a need for consistent cancellation and error handling.

For a small application, Angular's built-in HttpClient may be enough. An additional HTTP client is valuable only when its abstractions solve a real problem in your codebase.

References

What does your Angular application use for API requests: HttpClient, a custom wrapper, or a dedicated fetch client?

Author: Mohammad Garmabi — creator of tanstack-fetch, an independent TypeScript HTTP client.

Building Real-Time React Apps with SSE: Auth, Reconnection, and TanStack Query

Mohammad Garmabi — Sun, 11 Oct 2026 06:23:24 +0000

Real-time updates are easy to demonstrate. Making them work reliably in a real application is a different story.

You need to manage the connection lifecycle, handle authentication, decide what happens after a network interruption, and keep your UI in sync with server state.

Server-Sent Events (SSE) are a good fit when the server needs to push updates to the client over HTTP. But how should you integrate them into a React application that already uses TanStack Query?

1. Start with the right responsibilities

I like to separate real-time data into three concerns:

Transport: Establish the stream, receive events, and handle connection lifecycle.
Server state: Store and update the data the UI consumes.
Recovery: Decide whether to replay missed events or fetch the latest state again.

TanStack Query already handles much of the server-state lifecycle. The SSE connection should complement it, not become a competing cache.

2. Why not just use EventSource?

The native browser API is a reasonable starting point:

const source = new EventSource('/api/orders/stream');

source.onmessage = (event) => {
  console.log(JSON.parse(event.data));
};

source.close();

However, native EventSource doesn't let you attach arbitrary Authorization headers. That becomes a limitation when your API relies on bearer-token authentication.

A fetch-based SSE client can provide more control over request configuration and authentication.

3. Using tanstack-fetch for SSE

The framework-agnostic entry point is tanstack-fetch/sse.

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

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

const api = createFetch({
  baseUrl: 'https://api.example.com',
  plugins: ['sse-resume'],
  getToken: () => localStorage.getItem('access_token'),
});

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

// When the stream is no longer needed:
stream.close();

This example uses the documented client setup and streaming API. The actual event schema and server behavior depend on your backend.

The key benefit of this approach is that the stream can use a fetch-based transport rather than being limited to the native EventSource interface.

4. React integration with useSse

For React applications, the library also provides a framework-specific hook.

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

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

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

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

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

  return (
    <section>
      <p>Connection: {status}</p>
      <pre>{JSON.stringify(data, null, 2)}</pre>
      <button type="button" onClick={close}>
        Disconnect
      </button>
    </section>
  );
}

The hook exposes the latest data, connection status, error information, and a way to close the stream.

For Next.js App Router, use the hook inside a Client Component. Don't open browser-dependent streams inside server-side loaders or SSR code.

5. Where does TanStack Query fit?

A stream and a query solve different problems.

A query is useful for retrieving the initial state and recovering the latest server snapshot. SSE is useful for receiving changes as they happen.

For example, you could fetch an order using useQuery, then update the cache when a complete order snapshot arrives:

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

If an event only signals that the order changed, invalidating the query may be safer:

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

The right choice depends on your event contract. A partial event should not blindly replace a complete cached object.

6. Reconnection versus resume

These terms are often used interchangeably, but they describe different things.

Reconnection means opening the connection again after it fails.

Resume means continuing from a known position in the event stream so the client can recover events it missed.

A reconnecting client can still lose updates if the server doesn't support replay. Reliable resume generally requires event identifiers, server-side history, and a way to request events after the last processed position.

The sse-resume plugin is available in tanstack-fetch. Before relying on it in production, verify its exact behavior against your library version and the replay protocol implemented by your server.

7. When should you use SSE?

SSE is worth considering for:

Notification feeds
Order status changes
Live dashboards
Job progress indicators
Server-to-client event streams

If you need bidirectional communication, WebSockets may be a better fit. If updates are infrequent, ordinary queries or polling may be simpler.

Final thought

Real-time functionality isn't just about opening a stream. It's about deciding how transport, server state, authentication, and recovery work together.

I'm interested in how other React developers approach this:

Do you update the TanStack Query cache directly from SSE events, invalidate queries, or keep a separate event-driven state layer?

Docs and examples: https://mohamadgarmabi.github.io/tanstack-fetch/guide/sse

Disclosure: I'm the author of tanstack-fetch, an independent package and not an official TanStack project.

tanstack-fetch 1.7.0 — Solid / Angular / Svelte adapters + doctor CLI

Mohammad Garmabi — Fri, 09 Oct 2026 14:24:19 +0000

If you use TanStack Query, your queryFn wants: return data, throw on error, honor AbortSignal.

tanstack-fetch 1.7.0 ships real adapters for Solid, Angular, and Svelte (parity with React/Vue), a doctor CLI, more migrate scaffolds, onDownloadProgress, and docs that filter by framework.

Not an official TanStack package — shaped for the same Query API.

Upgrade

npm install tanstack-fetch@1.7.0

Adapters

import { useSse } from 'tanstack-fetch/solid'
// or tanstack-fetch/svelte · tanstack-fetch/angular

Import	API
`tanstack-fetch/solid`	`FetchProvider`, `useFetch`, `useSse`
`tanstack-fetch/svelte`	`setFetchClient`, `useFetch`, `useSse`
`tanstack-fetch/angular`	`provideFetchClient`, `injectFetch`, `useSse`

Doctor + migrate

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

Download progress

await api.get('/files/report.pdf', {
  parseAs: 'blob',
  onDownloadProgress: ({ progress, loaded, total }) => console.log(progress, loaded, total),
})

tanstack-fetch vs ky vs Axios: Which HTTP Client Fits TanStack Query?

Mohammad Garmabi — Wed, 07 Oct 2026 09:40:45 +0000

If you're using React + TanStack Query, you've probably written code like this:

queryFn: async ({ signal }) => {
  const { data } = await axios.get('/users', { signal })
  return data
}

Or with ky:

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

Both are perfectly valid.

But I kept asking myself:

Why does the HTTP client need to make my TanStack Query queryFn adapt its response?

That question led me to build tanstack-fetch.

The idea

TanStack Query is responsible for server state.

The HTTP client should be responsible for HTTP transport.

So the architecture becomes:

React
  ↓
TanStack Query
  ↓
tanstack-fetch
  ↓
Fetch

The HTTP client should fit naturally into the queryFn contract.

That means:

Return the actual data
Throw on HTTP errors
Support AbortSignal
Keep TypeScript types
Avoid unnecessary response transformations

Compare the APIs

Axios

queryFn: async ({ signal }) => {
  const { data } = await axios.get<User[]>('/users', {
    signal,
  })

  return data
}

ky

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

tanstack-fetch

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

The difference is small.

But across hundreds of query functions, small pieces of glue code add up.

Authentication is another problem

Real applications usually need more than:

fetch(url)

You may need:

Access tokens
Refresh tokens
Concurrent 401 handling
Request retries
Interceptors
SSR cookies
SSE
Request cancellation

For example, if five requests receive 401 simultaneously, you generally don't want five refresh requests.

You want:

401 ─┐
401 ─┤
401 ─┼──→ one refresh → retry requests
401 ─┤
401 ─┘

tanstack-fetch includes a refresh-token interceptor with single-flight behavior.

tanstack-fetch vs ky vs Axios

	tanstack-fetch	ky	Axios
TanStack Query focused	✅	❌	❌
Fetch-based	✅	✅	❌
Typed errors	✅	✅	✅
AbortSignal	✅	✅	✅
Token refresh	Built-in	Custom	Custom
Single-flight refresh	✅	Custom	Custom
SSR support	First-class	Manual	Manual
SSE	✅	Custom	Custom
Ecosystem	New	Mature	Very mature

This isn't about declaring a universal winner.

It's about choosing the right abstraction for your architecture.

When should you use tanstack-fetch?

It makes the most sense when:

You're already using TanStack Query
You want simpler queryFns
You want a typed Fetch-based client
You need auth refresh
You need SSR support
You need authenticated SSE
You're starting a new application
You're considering migrating from Axios, ky, ofetch, or Fetch

If you simply want a small Fetch wrapper, ky may be a better fit.

If you're already deeply invested in Axios, there may be no reason to migrate.

Migration

Migration is often harder than choosing a new library.

That's why tanstack-fetch includes a migration CLI that can scan existing HTTP call sites and help migrate Axios, ky, ofetch, and Fetch code toward a TanStack Query-oriented architecture.

The goal isn't:

Rewrite everything.

It's:

Make migration incremental and practical.

The bigger idea

I don't think every React application needs a new HTTP client.

But if TanStack Query is already the center of your data layer, your HTTP client should ideally complement it instead of forcing every query function to adapt between two different abstractions.

That's the idea behind tanstack-fetch.

TanStack Query → Server State

tanstack-fetch → HTTP Transport

Fetch → Network Primitive

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

If you're interested, check out the project and let me know what you think.

Migrate axios / ky / ofetch / fetch tanstack-fetch (CLI for TanStack Query)

Mohammad Garmabi — Mon, 05 Oct 2026 08:28:56 +0000

If you use TanStack Query, your queryFn wants: return data, throw on error, honor AbortSignal.

tanstack-fetch 1.6.2 ships a migrate CLI: scan axios / ky / ofetch / raw fetch, apply safe rewrites, and scaffold React, Vue, Nuxt, or Next.js.

Not an official TanStack package — shaped for the same Query API.

Quick start

npx tanstack-fetch migrate --from all --dir ./src
npx tanstack-fetch migrate --from axios --framework react --write --no-provider

// before
queryFn: async ({ signal }) => {
  const res = await axios.get('/users', { signal, params: { page: 1 } })
  return res.data
}

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

Flag	Meaning
`--from`	`axios` \
`--framework`	`react` \
`--provider` / `--no-provider`	React FetchProvider (default when asked: no)
`--write`	Safe transforms + scaffold

--write is conservative — review reported findings (query params, interceptors, res.ok).

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

Mohammad Garmabi — Sun, 04 Oct 2026 06:29:20 +0000

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

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

The request itself should be typed too.

Consider this:

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

At first glance, this looks type-safe.

But there is an important question:

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

And what happens if you accidentally write this?

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

The response type is correct.

The request is not.

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

What is tanstack-fetch?

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

It is not an official TanStack package.

The idea is simple:

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

The goal is not to replace TanStack Query.

Instead:

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

The problem with path parameters

Imagine a typical API:

GET /users/:id

We want the following to be valid:

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

type Params = {
  id: number;
};

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

But these should fail:

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

Because id is missing.

And:

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

Because the URL contains :id, not :userId.

And even this should fail:

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

The type and the URL don't agree.

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

What's new in 1.6.1?

Version 1.6.1 introduces typed URL parameters directly from the path.

For example:

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

type Params = {
  id: number;
};

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

Now the relationship between:

/users/:id

and:

{
  id: number
}

is explicit.

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

Response type + params type

You can keep both the response DTO and parameter map:

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

The first generic describes the response:

User

The second describes the path parameters:

Params

This gives you two independent layers of type safety:

URL
 ↓
params
 ↓
HTTP request
 ↓
response
 ↓
DTO

What about POST, PUT and PATCH?

The same idea also works for write operations.

For example:

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

type Params = {
  id: number;
};

type UpdateUser = {
  name: string;
};

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

Now we have three different types:

User
  ↓
Response

Params
  ↓
URL parameters

UpdateUser
  ↓
Request body

This makes the contract much more explicit.

Why not just use a route map?

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

createFetch<Routes>()

Version 1.6.1 removes that approach.

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

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

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

There is less global configuration and less ceremony.

A TypeScript limitation behind the API

There is an interesting TypeScript detail here.

TypeScript cannot partially infer generic parameters.

For example:

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

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

The practical result is that:

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

allows tanstack-fetch to preserve both:

the response DTO
the parameter map

That is why the API intentionally uses multiple type arguments.

What changed from 1.6.0?

The biggest change is actually a simplification.

1.6.0

The API experimented with:

createFetch<Routes>()

and a route map.

1.6.1

That approach is gone.

Instead:

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

The route itself becomes the source of truth.

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

Upgrade

If you're already using tanstack-fetch:

npm install tanstack-fetch@1.6.1

Or:

pnpm add tanstack-fetch@1.6.1

Why this matters

Type safety is often discussed in terms of response objects:

User
Product
Order

But an HTTP request has more than a response.

It has:

Method
URL
Path parameters
Query parameters
Request body
Headers
Response
Errors

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

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

/users/:id
       ↓
   { id: number }

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

Final thoughts

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

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

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

Version 1.6.1 is another step in that direction.

Not a huge feature.

Not another abstraction layer.

Just better type safety where it matters.

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

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

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

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

Mohammad Garmabi — Thu, 01 Oct 2026 13:41:18 +0000

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

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

Not an official TanStack package.

Quick start

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

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

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

SSE

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

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

Nuxt name clash

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

Bundle (gzip)

Entry	Size
HTTP	4.81KB
Vue	0.78KB
SSE	5.94KB

📦 npm · 📘 Vue guide · ⭐ GitHub

DEV Community: Mohammad Garmabi

I Redesigned the tanstack-fetch Website ✨

tanstack-fetch 1.7.1 Is Out: Timeouts, URL Params, Binary Bodies, and HTTP Errors

What's Changed?

1. URL parameters are matched more precisely

2. Timeouts are recognized as aborts

3. Timeout timers are cleaned up

4. Binary and stream request bodies work as intended

5. HTTP errors keep their real status

One Migration Detail

Try It

Building Production-Ready React Data Flows with tanstack-fetch and TanStack Query

1. Install the dependencies

2. Create a shared API client

3. Scenario one: Automatic token refresh

Implement the refresh-token interceptor

Why does this matter?

401 is not 403

4. Scenario two: Handle HTTP errors properly

Configure status-specific behavior

Display typed errors in React

5. Connect the API client to TanStack Query

6. Scenario three: Type-safe order management

Fetch an order

Define the query

Update an order with a mutation

7. Where does SSE fit?

8. The responsibility matrix

Final thoughts

TanStack Start 1.0 + tanstack-fetch: 6 Real-World Data Fetching Patterns

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

TanStack Start + TanStack Query: Sharing Data Between Loaders and Components

TanStack Start + TanStack Query: Sharing Data Between Loaders and Components

The core idea

1. Install the dependencies

2. Define reusable query options

3. Put QueryClient in router context

4. Load data before rendering

5. Configure the HTTP client for SSR

6. Handle mutations with the same cache

7. Authentication and token refresh

8. Add live updates with Server-Sent Events

9. What about tRPC?

10. What does tanstack-fetch actually simplify?

11. Migrate incrementally

12. Suggested project structure

Final thoughts

Angular API Requests with tanstack-fetch and TanStack Query

Angular API Requests with tanstack-fetch and TanStack Query

Install

Create the client

Provide it through Angular DI

Query data and pass AbortSignal

What's happening here?

What about authentication and retries?

When is this useful?

References

Building Real-Time React Apps with SSE: Auth, Reconnection, and TanStack Query

1. Start with the right responsibilities

2. Why not just use EventSource?

3. Using tanstack-fetch for SSE

4. React integration with useSse

5. Where does TanStack Query fit?

6. Reconnection versus resume

7. When should you use SSE?

Final thought

tanstack-fetch 1.7.0 — Solid / Angular / Svelte adapters + doctor CLI

Upgrade

Adapters

Doctor + migrate

`401` is not `403`