# TanStack Query + Next.js 16 App Router Prefetch (2026) To prefetch TanStack Query data in the Next.js App Router, call `prefetchQuery` on a per-request `QueryClient` inside a Server Component, then wrap the client subtree in ``. A matching `useQuery` on the client reads the data on first paint. ## TL;DR You will fetch a list on the server in the Next.js 16 App Router and hand it to the client without a loading flash. The build uses `next` 16.2.9, `react` 19.2.7, and `@tanstack/react-query` 5.101.0.[^npm] You create one `QueryClient` factory that is a fresh client per request on the server and a singleton in the browser, prefetch in a Server Component, serialize the cache with `dehydrate`, and rehydrate it through ``. You then set a non-zero `staleTime` so the client does not immediately refetch, and finish with a streaming variant that uses `useSuspenseQuery`. Budget about 25 minutes. ## What you'll learn - How to create a `QueryClient` factory that is per-request on the server and a singleton in the browser - How to wire the `QueryClientProvider` into the App Router with a `'use client'` Providers component - How to prefetch data in a Server Component with `prefetchQuery` - How `dehydrate` and `HydrationBoundary` move the server cache to the client - Why a prefetched query still refetches on mount, and how `staleTime` fixes it - How to stream a pending query with `useSuspenseQuery` and `shouldDehydrateQuery` - How to prefetch closer to where data is used, plus the single-client alternative - How to verify hydration worked, and how to fix the common failure modes ## Prerequisites - Node.js 20.9+ (Next.js 16 requires it; Node 24 LTS is the current Active LTS, supported through April 2028)[^node] - A new Next.js 16 App Router app: `npx create-next-app@16.2.9 my-app --ts --app` - Pinned packages, current on npm as of June 17, 2026:[^npm] ```bash npm install --save-exact @tanstack/react-query@5.101.0 @tanstack/react-query-devtools@5.101.0 npm install --save-exact -D typescript@6.0.3 @types/react@19.2.17 @types/react-dom@19.2.3 @types/node@24.13.2 ``` We will fetch from `https://jsonplaceholder.typicode.com`, a free public test API that needs no key, so every code block below runs as written. First, a small data layer. Create `lib/posts.ts`: ```ts export type Post = { id: number; title: string; body: string; }; const API = "https://jsonplaceholder.typicode.com"; export async function getPosts(): Promise { const res = await fetch(`${API}/posts?_limit=10`); if (!res.ok) throw new Error(`Failed to load posts: ${res.status}`); return res.json() as Promise; } ``` ## Step 1: Create a QueryClient factory that is per-request on the server A common App Router mistake is sharing one `QueryClient` across every request on the server. The server is long-lived, so a shared client leaks one user's data into the next user's cache. The fix is a factory that always builds a new client on the server, and reuses a single client in the browser. Create `app/get-query-client.ts`: ```ts import { environmentManager, QueryClient, defaultShouldDehydrateQuery, } from "@tanstack/react-query"; function makeQueryClient() { return new QueryClient({ defaultOptions: { queries: { // Above 0 so the client treats prefetched data as fresh // and does NOT refetch on mount. staleTime: 60 * 1000, }, dehydrate: { // Also ship queries that are still pending, so streaming works. shouldDehydrateQuery: (query) => defaultShouldDehydrateQuery(query) || query.state.status === "pending", }, }, }); } let browserQueryClient: QueryClient | undefined = undefined; export function getQueryClient() { if (environmentManager.isServer()) { // Server: a brand-new client for every request. return makeQueryClient(); } // Browser: reuse one client for the whole tab. if (!browserQueryClient) browserQueryClient = makeQueryClient(); return browserQueryClient; } ``` Two details matter here. `environmentManager.isServer()` is how current TanStack Query docs detect the server; in version 5.101.0 it is a function call. Older tutorials import a boolean instead (`import { isServer } from "@tanstack/react-query"` then `if (isServer)`) — that export still works but is now deprecated in favor of `environmentManager`, so do not let a copied snippet confuse you.[^isserver] The `staleTime` of 60 seconds and the `shouldDehydrateQuery` override both earn their place in later steps. ## Step 2: Wire up the QueryClientProvider `QueryClientProvider` uses React context, so it must live in a Client Component. Create `app/providers.tsx`: ```tsx "use client"; import { QueryClientProvider } from "@tanstack/react-query"; import { ReactQueryDevtools } from "@tanstack/react-query-devtools"; import { getQueryClient } from "./get-query-client"; export default function Providers({ children }: { children: React.ReactNode }) { // No useState: getQueryClient() already returns a stable per-tab client. const queryClient = getQueryClient(); return ( {children} ); } ``` Note the comment: do not wrap `getQueryClient()` in `useState`. The browser singleton already guarantees one stable client per tab, and `useState` adds nothing here. Then mount the provider once in `app/layout.tsx`: ```tsx import Providers from "./providers"; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` ## Step 3: TanStack Query server prefetching in a Server Component Now the heart of it. A Server Component creates a client, awaits the prefetch, and passes the serialized cache down through ``.[^ssr] Create `app/posts/page.tsx`: ```tsx import { dehydrate, HydrationBoundary } from "@tanstack/react-query"; import { getQueryClient } from "../get-query-client"; import { getPosts } from "../../lib/posts"; import PostList from "./posts"; export default async function PostsPage() { const queryClient = getQueryClient(); // Fetch on the server and warm the cache for this exact query key. await queryClient.prefetchQuery({ queryKey: ["posts"], queryFn: getPosts, }); return ( ); } ``` `prefetchQuery` runs `getPosts` on the server and stores the result under the key `["posts"]`. `dehydrate(queryClient)` serializes that cache into a plain object, and `HydrationBoundary` — itself a Client Component — rebuilds those entries into the browser client before your components render. The contract is the query key: the client must request the *exact* same key it was prefetched under. ## Step 4: HydrationBoundary and dehydrate on the client The client reads the cache with an ordinary `useQuery`. Because the entry was hydrated, the data is present on the first render — there is no loading state to flash. Create `app/posts/posts.tsx`: ```tsx "use client"; import { useQuery } from "@tanstack/react-query"; import { getPosts } from "../../lib/posts"; export default function PostList() { // Same queryKey as the server prefetch -> data is here on first paint. const { data, isPending, isError, error } = useQuery({ queryKey: ["posts"], queryFn: getPosts, }); if (isPending) return

Loading posts...

; if (isError) return

Something went wrong: {error.message}

; return (

{post.title}

); } ``` The `queryFn` is still here, and that is intentional: it is the fallback for client-side navigations to this route where no server prefetch ran, and the refetch source once the data goes stale. On the prefetched first load it simply is not called. ## Step 5: The staleTime that stops the double fetch Here is the subtle trap. TanStack Query's default `staleTime` is `0`, which means a query is considered stale the instant it is cached. So even with a perfect prefetch, the client mounts, sees a "stale" entry, and immediately refetches in the background — your server work was wasted and the network tab shows a duplicate request. Setting `staleTime` above zero in Step 1 is the fix: for the first 60 seconds the hydrated data is "fresh," so the client renders it and skips the refetch. You can confirm the mechanism directly. Right after a prefetch with `staleTime: 60 * 1000`, the cached query reports `isStale() === false`, which is exactly why no refetch fires on mount. Raise or lower the window to match how quickly your data changes; just keep it above zero whenever you prefetch. ## Step 6: Streaming a pending query with useSuspenseQuery Awaiting the prefetch blocks the response until the data is ready. For slower data you can instead *stream*: start the fetch, ship the still-pending query, and let it resolve over the wire into a Suspense boundary.[^ssr] This is why `makeQueryClient` overrode `shouldDehydrateQuery` to also include `pending` queries — the default drops them. Create `app/posts-streaming/page.tsx`: ```tsx import { dehydrate, HydrationBoundary } from "@tanstack/react-query"; import { Suspense } from "react"; import { getQueryClient } from "../get-query-client"; import { getPosts } from "../../lib/posts"; import StreamingPostList from "./posts"; // No `async`, no `await`: kick off the fetch and stream the result in. export default function StreamingPostsPage() { const queryClient = getQueryClient(); // Note: no await. The pending query is dehydrated and streamed. void queryClient.prefetchQuery({ queryKey: ["posts"], queryFn: getPosts, }); return ( Streaming posts...

}> ); } ``` The client component uses `useSuspenseQuery`, which never returns `undefined` data and suspends until the entry resolves. Create `app/posts-streaming/posts.tsx`: ```tsx "use client"; import { useSuspenseQuery } from "@tanstack/react-query"; import { getPosts } from "../../lib/posts"; export default function StreamingPostList() { // Suspends until ready; data is always defined here. const { data } = useSuspenseQuery({ queryKey: ["posts"], queryFn: getPosts, }); return (

{post.title}

); } ``` This works because React can serialize the pending promise to the client, and the `shouldDehydrateQuery` override puts the pending query into the dehydrated state in the first place. ## Prefetch closer to where data is used You are not limited to prefetching in `page.tsx`. Because Server Components nest, you can prefetch in `layout.tsx` or in any nested Server Component, dropping a `` around just the subtree that needs the data. Multiple boundaries on one page are fine — each can create its own client and dehydrate its own slice. The reason to prefetch deeper is parallelism: Next.js fetches route segments in parallel, so spreading prefetches across a layout, a page, and parallel routes lets the framework flatten what would otherwise be a server-side request waterfall.[^ssr] If you prefer one client for the whole request instead of one per Server Component, wrap a single factory in React's `cache`, which is scoped per request so nothing leaks between users: ```ts // app/get-query-client.ts (single-client-per-request alternative) import { QueryClient } from "@tanstack/react-query"; import { cache } from "react"; // cache() is scoped per request, so data never leaks between requests. export const getQueryClient = cache(() => new QueryClient()); ``` The tradeoff is that every `dehydrate(getQueryClient())` call serializes the *entire* client, including queries from unrelated Server Components, so you pay a little extra serialization for the convenience of grabbing the same client anywhere.[^ssr] ## Verification Run `npm run dev` and open `/posts`. Three checks confirm hydration worked: 1. **View source.** The rendered `

` titles are present in the initial HTML, not injected later by JavaScript. If the list is missing from the raw HTML, the prefetch did not run. 2. **Network tab.** On a hard reload of `/posts`, there is no client-side request to the posts API in the first 60 seconds. A duplicate request means `staleTime` is still `0`. 3. **React Query Devtools.** The `["posts"]` query appears already in a `success` state on first paint, rather than transitioning from `pending`. You can also verify the dehydration contract in isolation, without a browser. Save this as `verify.mjs` and run `node verify.mjs`: ```js import { QueryClient, dehydrate } from "@tanstack/react-query"; const sample = [{ id: 1, title: "first", body: "..." }]; // Awaited prefetch -> the query is captured with its data. const qc = new QueryClient(); await qc.prefetchQuery({ queryKey: ["posts"], queryFn: async () => sample }); console.log("queries dehydrated:", dehydrate(qc).queries.length); // 1 // A pending query is dropped UNLESS you opt it in. const qc2 = new QueryClient(); void qc2.prefetchQuery({ queryKey: ["posts"], queryFn: () => new Promise((r) => setTimeout(() => r(sample), 50)), }); console.log("default pending dehydrated:", dehydrate(qc2).queries.length); // 0 ``` The first log prints `1` and the second prints `0`. That second `0` is the exact reason streaming needs the `shouldDehydrateQuery` override from Step 1. ## Troubleshooting **`dehydrate()` returns an empty `{ queries: [] }`.** Either you did not `await` the prefetch (so the query was still pending when you dehydrated, and the default config drops pending queries), or you dehydrated a *different* `QueryClient` than the one you prefetched on. Await the prefetch for the blocking pattern, or add the `pending` override and a Suspense boundary for the streaming pattern.[^issue] **The data is correct, but the client refetches immediately on mount.** This is the `staleTime: 0` default. Set a non-zero `staleTime` in `makeQueryClient` so hydrated data is treated as fresh.[^ssr] **`environmentManager.isServer is not a function`.** You are on a TanStack Query version older than the one that introduced `environmentManager` (added in pull request #10199). Either upgrade to 5.101.0, or use the still-exported boolean instead: `import { isServer } from "@tanstack/react-query"` and `if (isServer)`.[^isserver] **The query key does not match.** Hydration is keyed by the serialized query key. `["posts"]` on the server and `["posts", undefined]` on the client are different keys, so the client treats the entry as a miss and fetches again. Keep the keys byte-for-byte identical. **You tried to fetch with a Server Action in the `queryFn`.** TanStack Query advises against this: Server Actions run serially when called from the client, which conflicts with how Query fetches and refetches, and can leave a query stuck pending. Fetch from a route handler or an RPC layer instead, and reserve Server Actions for mutations.[^serveraction] ## Next steps and further reading You now have server-prefetched, hydrated TanStack Query data with no loading flash and no duplicate fetch. From here, pair this with [Next.js 16 streaming and Suspense with `use cache`](/posts/nextjs-16-streaming-suspense-use-cache-tutorial) to control how the streamed shell renders, and use [Server Actions and optimistic UI in Next.js 16](/posts/nextjs-16-server-actions-react-19-optimistic-ui-tutorial) for the mutation side that `useMutation` pairs with. If you also use TanStack Router, the same key-based discipline shows up in [type-safe search params with TanStack Router](/posts/tanstack-router-type-safe-search-params-zod-tutorial). [^npm]: Versions confirmed on the npm registry on 2026-06-17: `next` 16.2.9, `react`/`react-dom` 19.2.7, `@tanstack/react-query` and `@tanstack/react-query-devtools` 5.101.0, `typescript` 6.0.3, `@types/react` 19.2.17, `@types/react-dom` 19.2.3, `@types/node` 24.13.2. [^node]: Node.js release schedule (Node 24 "Krypton" Active LTS): — and Next.js 16 declares `engines.node` `>=20.9.0`. [^ssr]: "Advanced Server Rendering," TanStack Query v5 React docs (the `get-query-client`, `staleTime`, `shouldDehydrateQuery`, and streaming patterns): [^isserver]: In `@tanstack/react-query` 5.101.0, `environmentManager.isServer` is a function and the older `isServer` is a boolean; both are exported, and the boolean `isServer` is now deprecated in favor of `environmentManager.isServer()` (TanStack/query PR #10199). Verified against the installed package. [^serveraction]: TanStack Query's Advanced Server Rendering guide warns against using Next.js Server Actions to fetch inside a `queryFn` (it cites issues TanStack/query #7934 and #6264): [^issue]: Recurring App Router reports that a prefetched query still refetches on the client on mount, or that `HydrationBoundary` fails to deliver prefetched data to a consumer: TanStack/query Discussion #7184 ("useQuery fetches in client upon mount") and Issue #8479 ("HydrationBoundary not working if prefetched query accessed via layout").

#hydration

TanStack Query + Next.js 16 App Router Prefetch (2026)