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?

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

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.

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?