How does useSuspenseQuery behave during SSR in App Router?

[pepperdad]

Hi! I'm using Next.js with the App Router, and I’ve been wondering how useSuspenseQuery operates during server-side rendering (SSR).

Here’s my question

How exactly does useSuspenseQuery behave during Server-Side Rendering (SSR)?

My setup

// page.tsx
import ClientComponent from './_component/ClientComponent';

export const Page = () => {
  return <ClientComponent />;
};

// ClientComponent.tsx
'use client';

import { useSuspenseQuery } from '@tanstack/react-query';
import { randomOptions } from '@/shared/data/getTodoItem/queries';

export default function ClientComponent() {
  console.log('@@@ in client component before query');
  const { data: randomData } = useSuspenseQuery(randomOptions());
  console.log('@@@ in client component after query', randomData);

  return (
    <>
      <h2>Client Component</h2>
      <p>randomData id: {randomData.id}</p>
      <p>randomData todo: {randomData.todo}</p>
    </>
  );
}

In this case, I expected that the useSuspenseQuery hook in the ClientComponent would not be executed during the SSR phase.
However, when checking the server logs in the Next.js environment, I saw logs data fetching called.

This made it appear as if useSuspenseQuery was actually executed on the server. Furthermore, after the page loaded in the browser, the same API was called again, and since the randomData returned was different, a hydration mismatch occurred.

To be more specific, when observing the behavior visually, the HTML returned from the server includes empty data, but the content shown on the screen contains the randomData that was fetched on the server. After that, the client triggers the API call again, and since the returned data differs, a hydration mismatch occurs.
https://github.com/user-attachments/assets/b34a722c-2e27-4a0b-a578-133c19fd6a4a

Does useSuspenseQuery perform an API call during SSR? I'm curious about how it actually works under the hood.
(I confirmed that switching to useQuery does not behave the same way.)

[pepperdad]

This problem still occurs even when the <ClientComponent /> is wrapped inside a <Suspense> boundary, like

import { Suspense } from 'react';
import ClientComponent from './_component/ClientComponent';

export const Page = () => {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <ClientComponent />
    </Suspense>
  );
};

export default Page;

[TkDodo]

Does useSuspenseQuery perform an API call during SSR?

yes, because client components also render on the server during SSR, and useSuspenseQuery throws a promise during render that nextJs picks up on.

Everything you said is expected. Please read the docs on SSR, especially the advanced ssr guide around streaming. You have to get data into the client cache somehow, and we offer multiple ways to do so.

[pepperdad]

@TkDodo
Thanks for your reply.
I fully understand that client components also render on the server during SSR.

However, I have one question.
When I switch from useSuspenseQuery to useQuery, I noticed that the queryFn is not executed on the server, which I confirmed through logging.

Is this because useSuspenseQuery triggers the API call on the server due to the internal behavior of useBaseQuery, specifically this part?

And on the other hand, does useQuery defer the API call until after the browser renders, because of this part that relies on useEffect?

[TkDodo]

yes, exactly.