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.

[TkDodo]

"I have data that comes from an RSC that I never want to update client-side"

why is that a common case? Do you want to let the RSC compute stuff, send it to the client and then just ignore it there? If that’s the case, why not just not compute it in the first place? That’s what the nextJs caching is for...

[TrevorBurnham]

Do you want to let the RSC compute stuff, send it to the client and then just ignore it there?

The RSC can only render DOM, not interactive components. So there are plenty of use cases where you want to send data to be used in client-side JavaScript. For example, let's say that you want to render a chart. The RSC could render a static representation of it, but if you want users to be able to manipulate the chart (zoom in and out, apply filters…), then the client-side JavaScript needs the raw data.

[TkDodo]

yes, but if you have zoomed in to your chart and applied filters on the client, then navigate to a different page, then go back to the page with the chart, nextJs will execute the server component and will send down the static version again, hydrating it again to become interactive. At that point, you have lost your zoom and filters. You want to preserve them, but for this to work, you need to “ignore” what RSCs are doing.

seems like you’re just a bit at odds with how nextJs has designed their approach to RSCs. They are a server first framework, so every navigation goes to the server and executes the RSC there and returns them in the RSC payload format.

TanStack Start for example has a different approach (no support for RSC yet though), where an app is often client-first and the server is only added for first renders and server functions.

[TrevorBurnham]

I do agree that TanStack Start is, conceptually, a better fit for client-first applications. I considered migrating from Next.js to it, but the current lack of custom server support is a dealbreaker for me: TanStack/router#3777

Since RSCs are on the agenda for TanStack Start, I assume it'll run into this same issue: Streaming data to the client during SSR is a nice TTI optimization, and you may not need/want to refetch that data from the client (as useSuspenseQuery assumes).

[TkDodo]

TanStack start will have a different take on server components: They will likely be seen like any other data format that you can get into the queryCache.