How should component-owned queries execute directly on the server with streamed hydration in Next.js?

[dBianchii]

Initially, I was tempted to title this discussion “TanStack Query’s SSR data-fetching model was not made to work with Next.js.” But that felt a little harsh without a proper discussion or without fully knowing if I am missing something or not.

There seems to be a mismatch between React Query’s recommended SSR model for Next.js and the granular, component-owned data-fetching model encouraged by the Next.js App Router.

Unlike some other frameworks, Next.js really discourages you to fetch all of the data you need for a given page. It seems that the framework would much rather have you fetch all of the data that each subtree or component needs for itself, instead of having all the data fetching be something owned by the route itself.

Next.js encourages fetching data in the component or subtree that consumes it. Identical fetch requests are memoized, while Suspense boundaries can be placed close to slow dynamic regions so the static shell renders immediately.

Consider an order-details page with a static layout and several independently loading regions:

<PageWithHeaderLayout
	header={
		<Suspense fallback={<OrderHeaderSkeleton />}>
			<OrderHeader />
		</Suspense>
	}
>
	<Suspense fallback={<FulfillmentSkeleton />}>
		<OrderFulfillment />
	</Suspense>

	<Suspense fallback={<ProductionHistorySkeleton />}>
		<ProductionHistory />
	</Suspense>

	<Suspense fallback={<OrderInformationSkeleton />}>
		<OrderInformation />
	</Suspense>
</PageWithHeaderLayout>

Each dynamic component needs the same order object:

function OrderHeader() {
	const { data } = useSuspenseQuery(orderDetailsQueryOptions(orderId));

	return /* ... */;
}

The desired behavior is for the first subscriber to start the query during server rendering.

1. The first subscriber starts the query during server rendering.
2. React Query deduplicates sibling calls using the query key.
3. The server executes the query directly against the server-side data source or procedure.
4. Each Suspense boundary independently controls its fallback.
5. The result streams into the browser’s QueryClient.
6. The browser does not immediately repeat the request.

The prefetch model

The currently recommended React Query SSR pattern is for a Server Component to prefetch the query and render a HydrationBoundary:

export default function Page() {
	const queryClient = getQueryClient();

	queryClient.prefetchQuery(serverOrderDetailsQueryOptions(orderId));

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

This works, including streaming pending queries in recent versions, but route-level prefetching (higher order RSC like described above) has an important consequence in Next.js: the request-time data access happens in a single RSC parent, outside the granular Suspense boundaries that describe the page’s loading behavior.

That defeats the purpose of structuring the page like this:

<StaticPageLayout>
	<Suspense fallback={<HeaderSkeleton />}>
		<DynamicHeader />
	</Suspense>

	<Suspense fallback={<ReportSkeleton />}>
		<DynamicReport />
	</Suspense>
</StaticPageLayout>

The Suspense boundaries suggest that the static layout and each dynamic region can be rendered independently. However, a route-level prefetch moves the actual request-time dependency above all those boundaries.

You could then say, (and this is the best I could come up with so far) that we could move the prefetching down into each subtree:

async function OrderHeaderBoundary() {
	const queryClient = getQueryClient();

	await queryClient.prefetchQuery(
		serverOrderDetailsQueryOptions(orderId),
	);

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

The page could then render it under Suspense:

<Suspense fallback={<OrderHeaderSkeleton />}>
	<OrderHeaderBoundary />
</Suspense>

This preserves the granularity expected by Next.js, but it feels like the wrong abstraction.
Every dynamic region now requires a Server Component whose only job is to prefetch, coupled with a hydration boundary colocated with that prefetch. Placing multiple Hydration boundaries like that feels quite wrong.

This is where the two models appear incompatible:

• Next.js wants request-time data access to happen inside the smallest subtree that actually needs it, with Suspense defining the dynamic boundary.
• React Query’s documented SSR model wants a Server Component ancestor to discover and prefetch the query, then explicitly hydrate its descendants.
• Moving that ancestor upward makes too much of the route dynamic.
• Moving it downward requires a prefetch-and-hydration wrapper around every independently loading subtree.

Neither option produces the component-owned model shown in the original example, where a component calls useSuspenseQuery, the first subscriber starts the server query, sibling subscribers share it, and the surrounding Suspense boundaries remain the only loading architecture.

[barry166]

The model you want is the experimental streamed hydration path, not the route-level prefetchQuery pattern.

Wrap the app in ReactQueryStreamedHydration from @tanstack/react-query-next-experimental and call useSuspenseQuery inside the client components under your local <Suspense> boundaries. On the initial render those queries can run on the server, dedupe by query key, stream into the browser QueryClient, and avoid an immediate client refetch if you set a non-zero staleTime.

<QueryClientProvider client={queryClient}>
  <ReactQueryStreamedHydration>{children}</ReactQueryStreamedHydration>
</QueryClientProvider>

The important boundary is the query function: because it lives in a client component module, don't import DB/server-only code there. If the query needs a server-only procedure, expose that through a route handler/server function/RPC endpoint, or keep a small Server Component prefetch wrapper at the subtree boundary.

Docs: https://tanstack.com/query/v5/docs/framework/react/guides/suspense#suspense-on-the-server-with-streaming

[dBianchii]

I'm glad you brought up ReactQueryStreamedHydration. In fact, I knew that was the right direction for all of this.

What I'm failing to see is how the queryFn can become "isomorphic", in a way where the server executes a procedure directly, while the client side queryFn can run the regular http request if needed. I don't think that running an http request through the same server is a good solution.

I am using tRPC, so for me it's really simple to:

• On the server, call the procedure directly (see https://trpc.io/docs/typedoc/tanstack-react-query/functions/createTRPCOptionsProxy)
• On the client, call the tRPC procedure through HTTP

ReactQueryStreamedHydration does solve the Suspense and hydration architecture neatly, but it does not solve the direct server execution requirement.

Is there a way to ensure that the server can fetch the data directly as I described? If not, then isn't this a clear indication that the library is missing some primitive for Next.JS or that it is just incompatible with the Next.JS RSC model?

[TkDodo]

This works, including streaming pending queries in recent versions, but route-level prefetching (higher order RSC like described above) has an important consequence in Next.js: the request-time data access happens in a single RSC parent, outside the granular Suspense boundaries that describe the page’s loading behavior.

I’m not really sure that this is the case. The way I see it, calling prefetchQuery does not / should not trigger a suspense boundary. It just starts the promise and streams it into the cache on the client.

The suspension happens where useSuspenseQuery is called, which can be inside different suspense boundaries.

If that’s not the case, please show a reproduction.

Initially, I was tempted to title this discussion “TanStack Query’s SSR data-fetching model was not made to work with Next.js.” But that felt a little harsh without a proper discussion or without fully knowing if I am missing something or not.

I am the first one to state / admit that React Query was not specifically made to work with nextJs. It’s a client-side async state manager that predates the app router by years. If you fully embrace the nextJs model, including cache components, why would you need React Query?

[dBianchii]

The way I see it, calling prefetchQuery does not / should not trigger a suspense boundary

You’re right that prefetchQuery() itself doesn’t trigger a Suspense boundary. My point is that an authenticated server-side query first needs access to runtime request data such as cookies(). With Cache Components, that request-time access must occur in a Server Component beneath Suspense.

That leaves the architectural concern: if I perform the authenticated prefetch at route level, I lift the dynamic dependency above the granular boundaries. If I move it into each subtree, every independently loading region needs a prefetching Server Component and a HydrationBoundary.

If you fully embrace the nextJs model, including cache components, why would you need React Query?
Cache Components and React Query solve different problems for us.

We use Next.js for server rendering, authentication, the static shell, streaming, and server-side caching. But after hydration, our app (Artelo) is a long-lived interactive application. React query handles all of the subsequent data requests and keeps the application with fresh data and appropriate loading states.

I am the first one to state / admit that React Query was not specifically made to work with nextJs

Interesting to see you say that. Am glad you are on the same page regarding it.

The missing piece I’m trying to describe is a supported bridge where the same component-owned query:

1. executes directly against its server-side data source using the authenticated request context during SSR;
2. streams into the browser QueryClient; and
3. uses its normal client-side query function for subsequent refetches

without requiring explicit hydration wrappers around every dynamic subtree

[TkDodo]

My point is that an authenticated server-side query first needs access to runtime request data such as cookies(). With Cache Components, that request-time access must occur in a Server Component beneath Suspense.

So can’t you add a Suspense Boundary around the page, then call cookies() there, then do the hydrate part once and then have more fine-grained SuspenseBoundaries beneath?

<StaticPageLayout>
  <Suspense>
    <OrderDetailsPage <-- server component that calls cookies
      <Suspense fallback={<HeaderSkeleton />}>
        <DynamicHeader />
      </Suspense>

      <Suspense fallback={<ReportSkeleton />}>
        <DynamicReport />
      </Suspense>
    </OrderDetailsPage>
 </Suspense>
</StaticPageLayout>

But yeah, that would probably opt you out of further static content inside OrderDetailsPage I guess?

The missing piece I’m trying to describe is a supported bridge where the same component-owned query:

1. executes directly against its server-side data source using the authenticated request context during SSR;
2. streams into the browser QueryClient; and
3. uses its normal client-side query function for subsequent refetches

The way I see it, Next is not specifically designed for this flow. The ideal flow in nextJs has 3) also do subsequent re-fetches by doing a full server roundtrip. With cacheComponents, you get something that is very similar to staleTime in React Query: The cacheComponents cache lives in the browser too, so with aggressive prefetching and cacheComponents and their “instant navigations”, you can get this behaviour from nextJs directly without using client-side fetching.

That said, I also like this flow you described, and it’s one of the reasons why TanStack Start exists, as it embraces this flow: loaders run on the server during SSR, data gets streamed directly into the client-side Query Cache on first load, and for subsequent, client-side navigations, the loader just runs on the client. Combined with server functions used in the queryFn, the function will be invoked directly on the server and turned into a fetch call on the client.

[dBianchii]

So can’t you add a Suspense Boundary around the page, then call cookies() there, then do the hydrate part once and then have more fine-grained SuspenseBoundaries beneath?

Yes, but that defeats the entire purpose of Cache Components, which is to have as much as possible of the static content be placed outside ≤Suspense/>, so that all of it can be thrown into a CDN by the hosting provider, as you said yourself.

That said, I also like this flow you described, and it’s one of the reasons why TanStack Start exists

It seems that we are in agreement that this is particularly hard in Next.JS then. I agree a similar result can be achieved with just native cacheComponents.

Given that we want to remain on Next.js and accept that it wasn’t designed specifically for this flow, what would you consider the best supported approach today?

As I understand it, there are only two available options, (and only the first one doesn't look hacky):

1. Move prefetching into Server Components colocated with each dynamic subtree. This preserves granular static and streaming boundaries, but requires repeated prefetch-and-hydration wrappers.
2. Use ReactQueryStreamedHydration and let useSuspenseQuery() initiate the query during SSR. This preserves component ownership, but the query function must also be client-compatible, so server rendering cannot execute directly against a server-only data source without some additional environment-aware bridge. This would require some complex workarounds to ensure the queryFn is "isomorphic".
3. Something else you recommend? (besides moving to TanStack Start 😅)

Is one of these the approach you would recommend for production use? Or is there another composition that better fits React Query’s intended Next.js integration?

[TkDodo]

I would not use the StreamedHydration package. It builds on a nextJs specific API and we haven’t really worked in that direction lately. It’s also quite magic. Moving prefetching down is an idea, TanStack Start is an idea, or not using Query is also an idea.