TanStack Query: Prefetching and SSR

TanStack Query: Prefetching and SSR

Hydrate the client cache from server-fetched data using dehydrate/hydrate and HydrationBoundary

When to Use

• Eliminating loading spinners by pre-populating the cache with server-fetched data
• Integrating TanStack Query with Next.js App Router Server Components
• Prefetching data on hover before a user navigates to a page
• Passing server-rendered data to client-side queries without a separate API round-trip

Instructions

1. In Next.js App Router, create a QueryClient in the Server Component and prefetch data with queryClient.prefetchQuery().
2. Pass the dehydrated state to a <HydrationBoundary> component — it hydrates the client-side QueryClient automatically.
3. Use dehydrate(queryClient) from @tanstack/react-query to serialize the cache for transport to the client.
4. In Client Components, call useQuery() with the same key used during prefetch — the data is available immediately with no loading state.
5. Use queryClient.prefetchQuery() (not ensureQueryData) when you do not need the return value — it avoids an extra await.
6. Prefetch on hover using queryClient.prefetchQuery() in a onMouseEnter handler to warm the cache before navigation.
7. Set staleTime to match your revalidation window — data prefetched at render time should not immediately re-fetch on mount.

// app/posts/page.tsx — Server Component with prefetch
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';
import { postListOptions } from '@/queries/posts';
import { PostList } from './post-list';

export default async function PostsPage() {
  const queryClient = new QueryClient();

  // Prefetch on the server — data is fetched once, not per-component
  await queryClient.prefetchQuery(postListOptions({}));

  return (
    // Injects dehydrated cache into the page
    <HydrationBoundary state={dehydrate(queryClient)}>
      <PostList />
    </HydrationBoundary>
  );
}

// app/posts/post-list.tsx — Client Component, no loading state
'use client';
import { useQuery } from '@tanstack/react-query';
import { postListOptions } from '@/queries/posts';

export function PostList() {
  // Data is immediately available — cache was hydrated from server
  const { data: posts } = useQuery(postListOptions({}));
  return <ul>{posts?.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
}

// Prefetch on hover — warm cache before navigation
function PostLink({ id }: { id: string }) {
  const queryClient = useQueryClient();
  return (
    <Link
      href={`/posts/${id}`}
      onMouseEnter={() => queryClient.prefetchQuery(postDetailOptions(id))}
    >
      View Post
    </Link>
  );
}

Details

TanStack Query's SSR pattern solves the classic problem: server-rendered HTML contains data, but the client-side React Query cache is empty on mount, causing a flash of loading state as queries re-execute.

Dehydration/hydration mechanism: dehydrate(queryClient) serializes successful query results into a plain JSON-serializable object. <HydrationBoundary state={dehydratedState}> deserializes it into the client's QueryClient on mount. The client queries then find their data already in cache and skip the initial fetch.

staleTime is critical for SSR: Without staleTime, TanStack Query considers all queries stale immediately on mount and triggers background refetches — wasting the server prefetch. Set staleTime to at least as long as the server render takes (e.g., Infinity for fully static data, or a few minutes for semi-fresh data).

New QueryClient per request: In Server Components, create a new QueryClient() per page render, not a shared singleton. A singleton would leak data between user requests in a server-side Node.js process.

Multiple prefetches: Prefetch all queries needed by a page segment at once using Promise.all:

await Promise.all([
  queryClient.prefetchQuery(postListOptions({})),
  queryClient.prefetchQuery(categoriesOptions()),
]);

Router-level prefetch: For non-Next.js apps, TanStack Router has built-in prefetch integration via loader functions that call ensureQueryData. This achieves the same effect without manual dehydrate/hydrate wiring.

Source

https://tanstack.com/query/latest/docs/framework/react/guides/prefetching

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.