TanStack Query v5: The New API and Why stale-while-revalidate Changes Everything

TanStack Query v5 unifies the hook API, adds queryOptions() for type-safe reuse, and makes stale-while-revalidate the default mental model for server state in React.

Mahmudul Haque Qudrati

CEO & ML Engineer

May 3, 2026

7 min read

// tags

#tanstack-query#react-query#data-fetching#caching#v5

FIG. ART-23

7 min read

“

TanStack Query v5: The New API and Why stale-while-revalidate Changes Everything

// reading plan

sections

487

words

min read

// Web Development

How to Build an MCP Server in TypeScript (Step-by-Step)

Build your first MCP server in TypeScript with the official SDK — tools, stdio transport, and a Claude Code test loop in under an hour.

5 min read

// Developer Tools

Redis Guide for Developers: Not Just a Cache

`queryOptions()` for Type-Safe Reuse

Define queries once and reuse them in hooks and prefetch calls with full type inference:

// lib/queries/tasks.ts
import { queryOptions } from "@tanstack/react-query";

export const taskQueries = {
  list: (projectId: string) =>
    queryOptions({
      queryKey: ["tasks", projectId],
      queryFn: () => api.tasks.list(projectId),
      staleTime: 30_000,
    }),

  detail: (taskId: string) =>
    queryOptions({
      queryKey: ["tasks", "detail", taskId],
      queryFn: () => api.tasks.get(taskId),
    }),
};

// In a component
const { data: tasks } = useQuery(taskQueries.list(projectId));

// In a server component for prefetch
await queryClient.prefetchQuery(taskQueries.list(projectId));

// In a mutation's onSuccess
queryClient.invalidateQueries(taskQueries.list(projectId));

Optimistic Updates

const createTask = useMutation({
  mutationFn: (data: NewTask) => api.tasks.create(data),

  onMutate: async (newTask) => {
    // Cancel in-flight refetches
    await queryClient.cancelQueries(taskQueries.list(projectId));
    // Snapshot current data
    const previous = queryClient.getQueryData(taskQueries.list(projectId).queryKey);
    // Optimistically update
    queryClient.setQueryData(
      taskQueries.list(projectId).queryKey,
      (old: Task[]) => [...old, { ...newTask, id: "temp", status: "pending" }]
    );
    return { previous };
  },

  onError: (err, vars, context) => {
    // Roll back on error
    queryClient.setQueryData(
      taskQueries.list(projectId).queryKey,
      context?.previous
    );
  },

  onSettled: () => {
    queryClient.invalidateQueries(taskQueries.list(projectId));
  },
});

Suspense Mode

v5 stabilizes Suspense integration - no more experimental flags:

import { useSuspenseQuery } from "@tanstack/react-query";

function TaskList({ projectId }: { projectId: string }) {
  // Throws a promise while loading  -  caught by parent Suspense
  const { data: tasks } = useSuspenseQuery(taskQueries.list(projectId));

  return <ul>{tasks.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
}

// Parent
<Suspense fallback={<Skeleton />}>
  <ErrorBoundary fallback={<Error />}>
    <TaskList projectId={id} />
  </ErrorBoundary>
</Suspense>

SSR With Next.js App Router

// app/projects/[id]/page.tsx
import { dehydrate, HydrationBoundary, QueryClient } from "@tanstack/react-query";
import { taskQueries } from "@/lib/queries/tasks";

export default async function ProjectPage({ params }: { params: { id: string } }) {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery(taskQueries.list(params.id));

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <TaskList projectId={params.id} />
    </HydrationBoundary>
  );
}

TanStack Query vs SWR

Feature	TanStack Query	SWR
Bundle size	~13KB	~4KB
Mutations	Full API	Manual
Optimistic updates	Built-in	Manual
Devtools	First-class	Third-party
Infinite queries	Built-in	Built-in
Suspense	Stable	Experimental
Learning curve	Medium	Low

SWR is great for simple fetching. TanStack Query wins when you need mutations, optimistic updates, or complex cache management.

References: TanStack Query · GitHub · v5 migration

TanStack Query v5: The New API and Why stale-while-revalidate Changes Everything

Related Articles

How to Build an MCP Server in TypeScript (Step-by-Step)

Redis Guide for Developers: Not Just a Cache

What Is Stale-While-Revalidate?

v5 Unified API

`queryOptions()` for Type-Safe Reuse

Optimistic Updates

Suspense Mode

SSR With Next.js App Router

TanStack Query vs SWR

The workspace your team
actually needs

AI & ML insights, weekly

Mahmudul Haque Qudrati

React Server Components: What They Are and When to Use Them

TanStack Query v5: The New API and Why stale-while-revalidate Changes Everything

Related Articles

How to Build an MCP Server in TypeScript (Step-by-Step)

Redis Guide for Developers: Not Just a Cache

What Is Stale-While-Revalidate?

v5 Unified API

queryOptions() for Type-Safe Reuse

Optimistic Updates

Suspense Mode

SSR With Next.js App Router

TanStack Query vs SWR

The workspace your teamactually needs

AI & ML insights, weekly

Mahmudul Haque Qudrati

React Server Components: What They Are and When to Use Them

`queryOptions()` for Type-Safe Reuse

The workspace your team
actually needs