pyRPC
← Back to Blog

Next.js RSC: prefetch, dehydrate, and HydrationBoundary

·11 min read

Server Components cannot call useQuery. They can still fetch data and seed the TanStack Query cache so the client hydrates without a flash refetch. That is what createNextClient’s server helpers are for.

The pipeline

  1. prefetch — run a query on the server into a request-scoped QueryClient.
  2. dehydrate — serialize that cache (TanStack API).
  3. HydrationBoundary — client boundary that rehydrates the cache.
  4. api.*.useQuery — reads warm data in a Client Component.
export default async function Page() {
  await api.prefetch.greet("Ada")
  return (
    <api.HydrationBoundary state={api.dehydrate()}>
      <Greeting />
    </api.HydrationBoundary>
  )
}

Prefetch ≠ mutations

Prefetch is for queries. Server-side writes use api.createCaller() (Promise client). Client mutations use api.update_user.useMutation().

When you can skip hydration

If you never prefetch on the server, you only need api.Provider + client hooks. Prefetch/dehydrate/HydrationBoundary are the fast path for SEO and first paint — not required for every page.

baseUrl on the server

RSC has no window. Always set baseUrl / PYRPC_URL for Next.

Full tutorial · One api object