Prefetching dependent queries with RSC and Suspense

[TrevorBurnham]

AFAICT the documentation doesn't cover the case where you want to perform multiple prefetch operations serially in an RSC, because one of the prefetch operations depends on the other.

I struggled to get this working in my app, but I was able to get it working by by forking the Next.js app with prefetching example to add a second query and a <Suspense> boundary. Here's the link:

• Streaming on Next.js 15 w/ React 19
• Same example on Next.js 14 w/ React 18 (appears to work, but the browser console reports "Warning: Maximum update depth exceeded." from the HydrationBoundary)

And here's a quick summary:

// function to generate options for the query to get a given Pokemon
export const getPokemonOptions = (id: number) =>
  queryOptions({
    queryKey: ["pokemon", id],
    queryFn: async () => {
      const response = await fetch(`https://pokeapi.co/api/v2/pokemon/${id}`);
      return response.json();
    },
  });

// code in the RSC to perform two serial fetch operations
void queryClient
  .fetchQuery({
    queryKey: ["favoritePokemonId"],
    queryFn: () =>
      // simulate database call to look up the user's favorite Pokemon
      new Promise<number>((resolve) =>
        setTimeout(() => resolve(Math.ceil(Math.random() * 100)), 500)
      ),
  })
  .then((favoritePokemonId) => {
    return queryClient.prefetchQuery(getPokemonOptions(favoritePokemonId));
  });

// code in the Suspense-wrapped client component to hydrate the data
const { data: favoritePokemonId } = useSuspenseQuery({
  queryKey: ["favoritePokemonId"],
  queryFn: (): number => {
    throw new Error("First queryFn in pokemon-info should never be called.");
  },
});
const { data: pokemon } = useSuspenseQuery({
  ...getPokemonOptions(favoritePokemonId),
  queryFn: () => {
    throw new Error("Second queryFn in pokemon-info should never be called");
  },
});

This works as I'd hoped: Everything outside of the <Suspense> boundary renders immediately, and the Suspense-wrapped component doesn't try to render until both pieces of data are available.

The only really clunky part is the need for a fake queryFn in the first useSuspenseQuery, even if I set staleTime to Infinity. AFAICT there's no way for me to explicitly say "I really only want to get this data on pageload, so I don't need a queryFn." Or am I missing something?

Update: Looking at this again, there's a bigger issue here: The queryFn for the second useSuspenseQuery gets called during SSR. I've filed a bug report: #8828

[TkDodo]

The only really clunky part is the need for a fake queryFn in the first useSuspenseQuery, even if I set staleTime to Infinity. AFAICT there's no way for me to explicitly say "I really only want to get this data on pageload, so I don't need a queryFn." Or am I missing something?

if you refetch this query, e.g. via invalidation, it will call the queryFn again. If the query gets garbage collected after not being used for quite some time, and you use it again, it will run the queryFn again. So yes, you need a queryFn to synchronize your view with the source of truth of the async state.

If you don’t want that, you probably don’t need React Query for this.

[TrevorBurnham]

If you don’t want that, you probably don’t need React Query for this.

I suppose I could set up my own context for the fetch promise and use use directly. 🤔 But, it's a common enough use case ("I have data that comes from an RSC that I never want to update client-side") that I'd expect TanStack Query to support it directly. Maybe it could be called useImmutableSuspenseQuery? It'd be essentially equivalent to useSuspenseQuery with staleTime: Infinity, no clientFn, and a type parameter for the data type (since it can't be derived from clientFn).