Tanstack Query prefetching with Nextjs cache components, dynamic searchParams, and separate hydration boundaries

[pauksztello]

Summary

I’m trying to use TanStack Query prefetching with Next.js Cache Components while keeping different parts of the page under separate <Suspense> and <HydrationBoundary> components.

The query key depends on searchParams, so I resolve the searchParams promise before passing the resulting plain object into a cached prefetch function.

Page implementation

import {
  type DehydratedState,
  dehydrate,
  HydrationBoundary,
} from "@tanstack/react-query";
import { type PropsWithChildren, Suspense } from "react";
import { getQueryClient } from "@/lib/tanstack-query/client";
import ItemsCount from "./items-count";
import ItemsList from "./items-list";
import type { Item } from "./use-items";

type Props = PageProps<"/[locale]/demo">;
type SearchParams = Awaited<Props["searchParams"]>;

async function listItems(searchParams: SearchParams): Promise<Item[]> {
  return [];
}

const prefetchItems = async (
  searchParams: SearchParams,
): Promise<DehydratedState> => {
  "use cache";

  const queryClient = getQueryClient();

  await queryClient.prefetchQuery({
    queryKey: ["items", searchParams],
    queryFn: () => listItems(searchParams),
  });

  return dehydrate(queryClient);
};

export default function Items({ searchParams }: Props) {
  const statePromise = searchParams.then((resolvedSearchParams) =>
    prefetchItems(resolvedSearchParams),
  );

  return (
    <div>
      <header>
        <h1>Items</h1>
      </header>

      <Suspense fallback={<p>Loading count...</p>}>
        <Hydrate statePromise={statePromise}>
          <ItemsCount />
        </Hydrate>
      </Suspense>

      <Suspense fallback={<p>Loading list...</p>}>
        <Hydrate statePromise={statePromise}>
          <ItemsList />
        </Hydrate>
      </Suspense>
    </div>
  );
}

async function Hydrate({
  children,
  statePromise,
}: PropsWithChildren<{
  statePromise: Promise<DehydratedState>;
}>) {
  const state = await statePromise;

  return <HydrationBoundary state={state}>{children}</HydrationBoundary>;
}

ItemsCount

"use client";

import useItems from "./use-items";

export default function ItemsCount() {
  const { data } = useItems();

  return <p>{data.length} items</p>;
}

ItemsList

"use client";

import useItems from "./use-items";

export default function ItemsList() {
  const { data } = useItems();

  if (data.length === 0) return <p>No items</p>;

  return (
    <ul>
      {data.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  );
}

useItems

"use client";

import { useSuspenseQuery } from "@tanstack/react-query";
import { useSearchParams } from "next/navigation";

export type Item = {
  id: string;
  name: string;
};

export default function useItems() {
  const searchParams = Object.fromEntries(useSearchParams().entries());

  return useSuspenseQuery({
    queryKey: ["items", searchParams],
    queryFn: async (): Promise<Item[]> => {
      return [];
      // NOTE: Fetch when search params change
    },
  });
}

getQueryClient implementation

import {
  defaultShouldDehydrateQuery,
  environmentManager,
  QueryClient,
} from "@tanstack/react-query";

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: { staleTime: Infinity },
      dehydrate: {
        // include pending queries in dehydration
        shouldDehydrateQuery: (query) =>
          defaultShouldDehydrateQuery(query) || query.state.status === "pending",
        shouldRedactErrors: () => {
          // We should not catch Next.js server errors
          // as that's how Next.js detects dynamic pages
          // so we cannot redact them.
          // Next.js also automatically redacts errors for us
          // with better digests.
          return false;
        },
      },
    },
  });
}

let browserQueryClient: QueryClient | undefined;

export const getQueryClient = () => {
  // Server: always make a new query client
  if (environmentManager.isServer()) return makeQueryClient();
  else {
    // Browser: make a new query client if we don't already have one
    // This is very important, so we don't re-make a new client if React
    // suspends during the initial render. This may not be needed if we
    // have a suspense boundary BELOW the creation of the query client
    if (!browserQueryClient) browserQueryClient = makeQueryClient();
    return browserQueryClient;
  }
};

Environment

Package versions

{
  "next": "16.3.0-preview.6",
  "@tanstack/react-query": "^5.101.2"
}

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactCompiler: true,
  cacheComponents: true,
  partialPrefetching: true,
  experimental: {
    useTypeScriptCli: true,
  },
};

export default nextConfig;

Goals

• Keep the page component synchronous so the static shell can render immediately.
• Keep request-dependent content inside <Suspense>.
• Preserve streaming.
• Cache the server-side query based on the resolved search parameters.
• Avoid calling connection().
• Keep separate parts of the page under their own Suspense and hydration boundaries.
• Avoid duplicating the server-side prefetch when multiple components consume the same query.
• Ensure both client components reuse the same hydrated TanStack Query cache entry.

Questions

1. Is resolving searchParams like this the intended approach?

const statePromise = searchParams.then((resolvedSearchParams) =>
  prefetchItems(resolvedSearchParams),
);

2. Is it safe and supported to pass the same Promise<DehydratedState> to multiple <HydrationBoundary> components?

3. Is "use cache" appropriate around the entire TanStack Query prefetch and dehydration function?

4. Would it be better to put "use cache" only inside listItems() and create the QueryClient and dehydrated state outside the cached function?

5. Could caching the dehydrated state cause issues because it contains query timestamps or other TanStack Query metadata?

6. Can hydrating the same query through multiple boundaries cause duplicated state, overwrites, or unexpected client-side behavior?

7. Is there a more idiomatic pattern for this case where the query key depends on asynchronous searchParams, but the page should still preserve streaming?

8. Will both ItemsCount and ItemsList correctly reuse the same hydrated query even though they are rendered under separate hydration boundaries?

I also opened the same discussion in Tanstack for additional feedback: TanStack/query#11083

Additional information

No response

Example

No response

[Olen7]

Great, well-structured question. The most important thing I'd flag is a subtle server/client query-key mismatch — everything else follows from that.

The key-parity bug (your Q8): your server and client build the query key differently, so they can silently diverge. Server-side the key is the resolved searchParams, where repeated params are arrays. Client-side you build it with:

ts
Object.fromEntries(useSearchParams().entries())

Object.fromEntries collapses repeated keys to the last value. You can confirm it in a console:

js
Object.fromEntries(new URLSearchParams("tag=a&tag=b").entries())
// => { tag: "b" }

So ?tag=a&tag=b becomes { tag: "b" } on the client but { tag: ["a", "b"] } on the server. TanStack hashes keys deterministically, so those two don't match → the hydrated entry is ignored and the client refetches, defeating the prefetch. If any of your params can repeat, normalize both sides to the same shape before building the key (e.g. always coerce to arrays, or use getAll explicitly).

On "use cache" placement (Q3–Q5): I'd move the cache boundary down to the pure data function rather than wrapping the whole prefetch/dehydrate. dehydrate output includes TanStack metadata such as dataUpdatedAt; caching the whole dehydrated state freezes those timestamps at cache-write time. With staleTime: Infinity you won't notice immediately, but it becomes a subtle staleness bug the moment you lower staleTime. Caching only listItems keeps the cached unit purely serializable data and lets the QueryClient/dehydration run fresh per request.

Passing one Promise to multiple HydrationBoundary (Q2, Q6): safe. The promise resolves once and all awaiters share the value; hydrate is idempotent per query key, so hydrating the same key through two boundaries won't duplicate or overwrite.

Reuse across separate boundaries (Q8): yes — both components read from the same singleton client and key, so they share one cache entry once the key parity above is fixed.

Simpler pattern (Q7): since both consumers share one query, you don't strictly need two HydrationBoundary — one boundary wrapping both children is enough. Separate boundaries only pay off when each streams a different dehydrated state.

Resolving searchParams (Q1): chaining off the promise to keep the page component synchronous is a reasonable way to preserve the static shell and streaming; just keep the object you feed into the key stable and serializable.

Since cacheComponents is still preview, the caching specifics may shift between canaries — but the key-parity issue is version-independent and worth fixing regardless. Hope this helps — let me know if normalizing the key resolves the missed hydration on your end.