Using setQueryData instead of initialData for populating query cache with server-side rendering (SSR)

[bennettdams]

TL;DR The docs are recommending setting initialData of a query when you want to use your already-fetched data from the server.

Why not use setQueryData? What are the disadvantages of using setQueryData in this context, respectively why is it not recommended in the docs?

---

I have a common use case: Creating an "Incremental static regeneration" page with Next.js that also fetches data from the database. Now, I can give that data down to the page via props as well. Usually, when this page renders, it also executes a useQuery down the tree, that's why I want to populate the query (well, the query's cache) with the data I already fetched on the server.

In the docs, there are two ways described on how to do this with Next.js.
I don't need the cache on the server, so I'm ignoring the hydration method for this question. I only want to talk about the first method: using initial data:

The downsides are already described in the docs, mainly that you have to move the data via props, maybe even multiple levels deep in your component tree.
So I thought: Why not use setQueryData? This gives me the benefits of easily being able to fill the cache independently, but also eliminates the need to pass down the data in the tree.

Using setQueryData directly in the Next.js page like so:

export const getStaticProps: GetStaticProps<MyPageProps, Params> =
  async () => {
    const myData = (await fetchSomeData()).result;

    return {
      props: {
        myData : myData ?? null,
      },
      revalidate: revalidateInSeconds,
    };
  };

export default function _MyPage(props: MyPageProps): JSX.Element {
  if (props.myData) {
    queryClient.setQueryData<QueryDataType>([queryKey], props.myData);
  }
  // SomePage will use "useQuery" inside
  return <SomePage myData={props.myData} />;
}

This works really well! The statically created page also contains the fetched data that way. Even if I disable the useQuery execution down in the tree, which shows me that the data was definitely filled via that "server cache". So based on e.g. the staleTime of the query, the data will not be fetched immediately when the page renders, because the cache is already filled with data from the server.

So my question is: What are the disadvantages of this method, respectively why is it not recommended in the docs?

---

Bonus question:

There's one thing I don't understand though: The onSuccess callback of useQuery is not executed that way.
The docs are saying that this callback is executed also when using setQueryData - but it is not in my case.

See this CodeSandbox.

The data with a useQuery inside looks like this. With A) you can toggle setQueryData with server data and with B) you can toggle fetching in useQuery

export default function IndexPage({ myData }) {
  // A)
  if (true) {
    queryClient.setQueryData([queryKeys.withServerData], myData);
  }

  return (
    <MyDataComponent
      // B)
      shouldFetchOnClient={true}
      dataFromServer={myData}
      queryKey={queryKeys.withServerData}
    />
  );
}

If you disable setQueryData (via A) (=false) ), there is no server data and every time you reload the page, the useQuery will refetch data and onSuccess is executed.

If both A) and B) are active (=true), you can see that the query cache is populated with the data from the server, but onSuccess is not executed, because the client does not execute the fetch via useQuery, as it's not stale.

Is that because I use setQueryData before the first instance of that cache's useQuery was mounted?
Am I using setQueryData wrongly? Or am I misunderstanding useQuery's onSuccess function? Or is this a bug?

[TkDodo]

I don't need the cache on the server, so I'm ignoring the hydration method for this question.

That is not what the hydration method is doing though :) By using it, you create a "temporary" cache that has the correct structure that your queries will have. By dehydrating it, you'e sending the correct structure to the client. The cache is created inside getStaticProps every time, so it doesn't really cache anything:

export async function getStaticProps() {
   const queryClient = new QueryClient()
 
   await queryClient.prefetchQuery('posts', getPosts)
 
   return {
     props: {
       dehydratedState: dehydrate(queryClient),
     },
   }
 }

I still think this is the easiest way to prefetch multiple queries on the server. Sure you could do the same thing with setQueryData, but it's pretty manual, and actually the same thing that the hydration is doing: Putting data into the cache on the frontend. Except that it already had the correct structure.

There's one thing I don't understand though: The onSuccess callback of useQuery is not executed that way.
The docs are saying that this callback is executed also when using setQueryData - but it is not in my case.

At the moment you call setQueryData, you don't have an active observer yet, because it will be rendered after that. So there is no onSuccess callback to call :)

Also, you can't really call setQueryData during rendering like you do in this sandbox. This violates the rules of react that a render function has to be pure. I guess that's one reason why we don't recommend it. You would need to setup a useEffect and delay the rendering of children by one render cycle to make it safe.

[bennettdams]

@TkDodo Thanks, great explanation, as always.
I have one follow-up question: How would you serialize Dates with that concept? With Next.js, this is a hard topic anyways, so a lot of people use superjson to "patch" the hydration process. With the concept you've described above, we're opting out of superjson's serialization, so every Date in the base data on the server will throw an error when using it for a query with React Query:

Do you recommend a specific concept or place to do the serialization manually? Or is there maybe a way to intercept the hydration on the client with our own global serialization methods?
I looked around issues, discussions and the internet, but found no answer.
Let me know if I should create a new discussion for that, so this question can be found by others.

[bennettdams]

I looked around issues, discussions and the internet, but found no answer.

This topic is mentioned in the docs as limitation, but I'm not sure about the solution.

In the example, <Hydration>.. is used in _app.jsx. This means that React Query's hydration can only ever work, if you never have unserializable data in any of your pages in getStaticProps getServerSideProps, e.g. the very first Date will make the hydration fail.
If we now say that one has to deserialize on his own (like written in the limitations), _app is also a bad place to do that, because the data will look different for every page, so handling the deserialization in this general entrypoint component is probably not a good idea.
What I did now was using <Hydrate>.. in the page where I also fill the query cache. That way I also have the deserialization in the same place, which allows type-safish execution.

What do you think?

PS: Do you have a recommendation to make the deserialization type-safe? Right now, neither dehydrate or <Hydrate>.. are implemented to be provided with a generic, so the QueryState's data is always unknown.

Example:

function fillQueryCacheOnServer(
  myData: MyData[] | null
) {
  if (!myData) {
    return null;
  } else {
    const queryClient = new QueryClient();

    queryClient.setQueryData<QueryDataType>(
      [queryKey],
      // serialization
      JSON.parse(JSON.stringify(myData))
    );

    return queryClient;
  }
}

export function createDehydratedState(
  myData: MyData[] | null
): DehydratedState | null {
  const queryClient = fillQueryCacheOnServer(myData);
  return !queryClient ? null : dehydrate(queryClient);
}

export function deserialize(myDataEntry: MyData): MyData {
  myDataEntry.someDate = new Date(myDataEntry.someDate);

  return myDataEntry;
}

export const getStaticProps: GetStaticProps<MyPageProps> = async () => {

  const myData = await fetchData().result ?? null

  return {
    props: {
      dehydratedState: createDehydratedState(myData),
    },
    revalidate: revalidateInSeconds,
  };
};

export default function MyPage(props: MyPageProps): JSX.Element {
  return (
    <Hydrate
      state={{
        ...props.dehydratedState,
        queries: props.dehydratedState.queries.map((query) => {
          // deserialization
          query.state.data = query.state.data.map((myDataEntry) => deserialize(myDataEntry));
          return query;
        }),
      }}
    >
      <div ... />
    </Hydrate>
  );
}

[bennettdams]

I created a separate discussion for that: #2872

[cmacdonnacha]

Hey @TkDodo

Separate to SSR, would you mind explaining when you would use initialData over setQueryData? Does one have an advantage over the other?

[TkDodo]

setQueryData sets data for a query unconditionally. If the query doesn't exist, it will be created.

initialData is an option on useQuery that will take that data and put it into the cache IF the query doesn't exist yet. It's used in the constructor of the Query class. So if a query already exists in the cache, initialData does nothing.