Prefetching with Nextjs cache components, dynamic searchParams, and separate hydration boundaries

[pauksztello]

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 Nextjs for additional feedback: vercel/next.js#95933

[Olen7]

Great, well-structured question. The most important thing I'd flag is a query-key parity issue between server and client — a few of your other questions resolve themselves once that's fixed.

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

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

Object.fromEntries collapses repeated keys to the last value. Easy to confirm:

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

So ?tag=a&tag=b produces ["items", { tag: ["a", "b"] }] on the server but ["items", { tag: "b" }] on the client. Since query keys are hashed deterministically, those are two different cache entries → the hydrated data is never matched, useSuspenseQuery treats it as a cache miss and refetches, silently defeating the whole prefetch. If any param can repeat, normalize both sides to one shape before building the key (e.g. coerce everything to arrays, or read with getAll explicitly).

One Promise<DehydratedState> into multiple HydrationBoundary (Q2, Q6): safe and supported. The promise resolves once and every awaiter gets the same value. hydrate is idempotent per query key — hydrating the same entry through two boundaries won't duplicate or overwrite state; the second hydration of an identical entry is effectively a no-op (existing data is only replaced when the incoming dehydrated data is newer).

Reuse across boundaries (Q8): yes. Both ItemsCount and ItemsList read from the same singleton browser QueryClient with the same key, so they share a single cache entry — once key parity above is fixed.

Simpler pattern (Q7): since both consumers share one query, two HydrationBoundary components don't buy you anything here — a single boundary wrapping both <Suspense> children is equivalent and simpler. Separate boundaries earn their keep only when each one streams a different dehydrated state (e.g. two independent queries resolving at different times).

Caching the dehydrated state (Q3–Q5): I'd avoid wrapping the whole prefetch+dehydrate in "use cache". dehydrate output includes per-query metadata such as dataUpdatedAt; caching the full DehydratedState freezes those timestamps at cache-write time. With staleTime: Infinity you won't notice, but it turns into a subtle staleness bug the moment you lower staleTime — hydrated queries will look "fresher" or "staler" than they really are. Cleaner: cache only the pure data function (listItems), and create the QueryClient + run prefetchQuery + dehydrate fresh per request. The cached unit stays purely serializable data; Query metadata stays honest.

Resolving searchParams via .then() (Q1): keeping the page component synchronous and chaining off the promise is a reasonable way to preserve the static shell and streaming — just keep the object you feed into the key stable and serializable (which ties back to the normalization point above).

Hope this helps — curious whether normalizing the key resolves the missed hydration on your end.