What are the best practices for data fetching when using tanstack-query in Next.js App router?

[H0onnn]

Hello,

I have one question when using the beautiful features provided by the document.
That is, when should I use prefetchQuery to fetch data?

Currently, I fetch all data using prefetchQuery in the RSC and use useSuspenseQuery everywhere it's consumed (on the client).

However, I'm unsure if this is the correct approach.

I'm genuinely curious how others handle this and what the best-practices are.

[tbhvishal]

Fetching all data through prefetchQuery in RSC and consuming it with useSuspenseQuery on the client is an anti-pattern. While it works, it introduces unnecessary serialization overhead, bloats the RSC Flight payload, and bypasses the primary architectural benefits of React Server Components.

The guiding mental model: RSC is your data fetcher; TanStack Query is your client-side async cache manager.

Here is the decision matrix and best practices for combining them cleanly in production:

---

1. The Decision Matrix

Scenario	Architectural Choice	Why?
Read-Only / Static Content (Blog posts, product details, landing pages, headers)	Pure RSC (async/await) No TanStack Query	Zero client JavaScript bundle size. The data is rendered to static HTML on the server and never ships to the client as cache state.
Interactive UI with Mutations / Refetching (Feeds with upvoting, comment lists, real-time dashboards)	prefetchQuery in RSC + <HydrationBoundary>	Delivers instant HTML from the server, then hands hydration over to TanStack Query so the client can do optimistic updates, polling, or refetch on window focus.
User-Interactive / Client-Dependent Data (Dropdown autocomplete, search inputs, modal forms)	Client-only useQuery No RSC prefetch	Avoids blocking server rendering for data that the user hasn't asked for yet.

---

2. When to use prefetchQuery in RSC

Use prefetchQuery only when the consuming component must be a Client Component ("use client") that requires TanStack Query features:

1. Optimistic Updates & Mutations: You need useMutation to update the list immediately upon user interaction without a full page navigation.
2. Refetching & Polling: You rely on refetchOnWindowFocus, refetchInterval (polling), or manual cache invalidation (queryClient.invalidateQueries).
3. Infinite Scrolling / Dynamic Pagination: Consuming useInfiniteQuery on the client where the initial page of items comes from the server.
4. Shared Cache Across Disconnected Client Widgets: Two separate interactive client components on the page need to synchronize against the same query key without prop drilling.

Production Pattern

// app/posts/page.tsx (Server Component)
import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
import { getQueryClient } from '@/lib/get-query-client';
import { PostsList } from '@/components/posts-list';

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

  // Prefetch only because PostsList has interactive client actions (voting, live comments)
  await queryClient.prefetchQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts,
  });

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

// components/posts-list.tsx (Client Component)
"use client";

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

export function PostsList() {
  // Reads instantly from dehydrated cache with 0 network waterfall on initial load
  const { data } = useSuspenseQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts,
  });

  return (
    <ul>
      {data.map((post) => (
        <PostCard key={post.id} post={post} />
      ))}
    </ul>
  );
}

---

3. Critical Production Gotchas

When using prefetchQuery with App Router, watch out for these three pitfalls:

A. The staleTime Invariant (The #1 Bug)

By default, TanStack Query sets staleTime: 0. If you do not configure a non-zero staleTime, the client will treat the server-dehydrated data as instantly stale the millisecond it hydrates—triggering an immediate duplicate fetch over the network!

Always set a default staleTime on your server/client QueryClient:

// lib/get-query-client.ts
import { QueryClient, defaultShouldDehydrateQuery, isServer } from '@tanstack/react-query';

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000, // Keeps initial server data fresh on mount
      },
      dehydrate: {
        // Include pending queries if streaming with Suspense
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
      },
    },
  });
}

B. Flight Stream Payload Inflation

Every byte stored in dehydrate(queryClient) is serialized into the RSC payload (the hidden <script> tag carrying the React Flight data). If you prefetch large static tables that never update, you are sending that data twice over the wire (once as HTML, and once as JSON state).

C. Request-Scoped Query Client

On the server, never declare a global singleton export const queryClient = new QueryClient(). Multiple incoming requests in Node.js would share the same instance, causing cache leaks across different users. Use React.cache() to scope the instance strictly to the current request lifecycle.