TanStack Query in the Next.js App Router: Prefetch and Hydrate

The Next.js App Router already lets a Server Component await a fetch call directly, so a fair question is why bother adding TanStack Query at all. The honest answer is that fetch alone gives you data on first load and nothing else — no background refetching, no cache invalidation after a mutation, no request deduplication across sibling components, and no built in retry or stale-data handling on the client. Once a page has any interactive piece, a filter, a form that saves and reloads a list, a status badge that should update without a full page refresh, plain fetch stops being enough and you end up hand-rolling the exact cache logic that TanStack Query already solved years ago.

TanStack Query still owns that entire client-side lifecycle, and the App Router gives you a clean way to seed its cache from the server so the first paint is never a loading spinner. This post walks through the exact prefetch, dehydrate, and hydrate flow for the App Router, when it earns its keep over a plain fetch, and the mistakes that quietly cause a page to fetch every query twice. Everything here assumes TanStack Query v5, which is the version that shipped first-class support for streaming pending queries through a Suspense boundary rather than only supporting a fully-awaited prefetch.

What prefetch, dehydrate, and hydrate actually do

Server rendering with TanStack Query is a three step handoff between the server and the browser. Each step has one job, and skipping any of them breaks the chain. It helps to think of it less as a special App Router feature and more as passing a pre-warmed cache as a prop, the same way you would pass any other server-computed value down to a Client Component.

• Prefetch: a Server Component creates a QueryClient and calls prefetchQuery, which runs the query function on the server and stores the result in that client's in-memory cache.
• Dehydrate: the populated cache is serialized into a plain, JSON-safe object that can be embedded in the server-rendered markup and sent down with the initial HTML.
• Hydrate: on the client, a HydrationBoundary reads that serialized state and loads it straight into the browser's QueryClient cache, before any component has a chance to call useQuery.

Setting up a per-request QueryClient

A QueryClient must never be a module-level singleton on the server, because every request would then share the same cache across different users. Instead, wrap the client factory in React's cache function so it is scoped to a single request on the server, and lazily created once in the browser. This also sets a non-zero staleTime, which matters more than it looks: without it, a hydrated query is considered stale the instant it lands in the browser, and useQuery immediately refires the request in the background, defeating the whole point of prefetching. The same factory function should be imported by every route that needs prefetching, rather than each route defining its own QueryClient options, so staleTime and retry behavior stay consistent across the app.

// lib/get-query-client.ts
import { QueryClient, defaultShouldDehydrateQuery } from "@tanstack/react-query"
import { cache } from "react"

// React's cache() scopes this to a single request on the server,
// and creates a fresh browser QueryClient the first time it runs on the client.
export const getQueryClient = cache(() => new QueryClient({
  defaultOptions: {
    queries: {
      // Prefetched data stays "fresh" for 60s so the client
      // does not immediately refetch on mount.
      staleTime: 60 * 1000,
    },
    dehydrate: {
      // Also dehydrate queries that are still pending, so we
      // can stream them and resolve on the client (see section 4).
      shouldDehydrateQuery: (query) =>
        defaultShouldDehydrateQuery(query) || query.state.status === "pending",
    },
  },
}))

Prefetching in a Server Component and hydrating a Client Component

The Server Component does the prefetch and wraps its children in a HydrationBoundary, passing in the dehydrated cache state. The Client Component underneath calls useQuery with the exact same queryKey and queryFn. If the key matches what was prefetched, useQuery reads directly from the hydrated cache and renders immediately with no network request and no loading state on first paint. Note that the queryFn itself still needs to exist in the Client Component even though it will not run on first load, because TanStack Query needs it available for any later refetch, whether that is triggered by a window refocus, a manual invalidate, or the staleTime window expiring.

// app/[locale]/(pages)/orders/page.tsx  — Server Component
import { HydrationBoundary, dehydrate } from "@tanstack/react-query"
import { getQueryClient } from "@/lib/get-query-client"
import { OrderList } from "./order-list"
import { getOrders } from "@/lib/orders"

export default async function OrdersPage() {
  const queryClient = getQueryClient()

  await queryClient.prefetchQuery({
    queryKey: ["orders"],
    queryFn: getOrders,
  })

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

// app/[locale]/(pages)/orders/order-list.tsx  — Client Component
"use client"
import { useQuery } from "@tanstack/react-query"
import { getOrders } from "@/lib/orders"

export function OrderList() {
  // Same queryKey and queryFn as the server prefetch — this
  // reads the hydrated cache instead of firing a new request.
  const { data: orders } = useQuery({
    queryKey: ["orders"],
    queryFn: getOrders,
  })

  return (
    <ul>
      {orders?.map((order) => <li key={order.id}>{order.reference}</li>)}
    </ul>
  )
}

Streaming a slow query instead of blocking on it

Awaiting every prefetchQuery call blocks the whole route until the slowest query resolves, which throws away one of the best features of the App Router: streaming. Instead, await only the queries that gate the above-the-fold content, and fire the slow ones without awaiting them. TanStack Query's dehydrate config can be told to also serialize queries that are still pending, which streams the in-flight promise to the client. A Client Component using useSuspenseQuery on that same key then simply resumes the already-started request inside a Suspense boundary, rather than starting a fresh one. This is the same mechanism React's own use API relies on for streaming a promise prop, TanStack Query just wraps it with caching, retries, and the rest of its query lifecycle on top.

// Streaming variant — do NOT await the slow query on the server.
export default async function DashboardPage() {
  const queryClient = getQueryClient()

  // Fast query: await it, it is ready before the HTML streams.
  await queryClient.prefetchQuery({
    queryKey: ["summary"],
    queryFn: getSummary,
  })

  // Slow query: fire it but do not await. The pending promise is
  // dehydrated and streamed to the client, which resumes it.
  queryClient.prefetchQuery({
    queryKey: ["annual-report"],
    queryFn: getAnnualReport,
  })

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <Summary />
      <Suspense fallback={<ReportSkeleton />}>
        <AnnualReport />
      </Suspense>
    </HydrationBoundary>
  )
}

// Client Component — suspends on the still-resolving stream
"use client"
function AnnualReport() {
  const { data } = useSuspenseQuery({
    queryKey: ["annual-report"],
    queryFn: getAnnualReport,
  })
  return <Report data={data} />
}

TanStack Query versus a plain fetch call

Reaching for TanStack Query on every Server Component is overkill. Use plain fetch or a direct database call when the data is only ever read once per request and never touched by client-side interactivity. Reach for TanStack Query when a Client Component needs to refetch, poll, invalidate after a mutation, or share the same query across components that do not have a common parent to pass props through. A good signal is whether you would ever need to call router.refresh just to reflect new data, if the answer is yes, that refresh is really a manual, worse version of what invalidateQueries already does.

Avoiding the double-fetch trap

The most common bug in this setup is a page that fetches the same data twice — once on the server during prefetch, and again on the client the moment the component mounts. It usually comes down to one of these four causes, and all four are easy to fix once you know to look for them.

1. Mismatched queryKey between the server prefetch and the client useQuery call, which the cache treats as two unrelated entries.
2. staleTime left at its default of zero, so the hydrated data is instantly stale and refetches on mount.
3. Creating a new QueryClient instance in the Client Component tree instead of relying on the single hydrated one from the QueryClientProvider.
4. Forgetting the HydrationBoundary entirely, so the dehydrated state from the server never reaches the browser cache in the first place.