Proposed React Query hydration changes for v4 / React 18

[Ephem]

Latest plans for hydration and SSR are now in this discussion

Update: After getting some great insight from Sebastian in the React Working Group I think we should try to put in the effort of implementing the "Possible alternative" described below. Still need to work out details and see what this means in practice though.

"A possible way to get around both hydrating in render and the negative downsides of useEffect could be to in addition to hydrating in useEffect also pass down the dehydratedState on a context. If some dehydratedState lives on that context, on cache read we merge that temporarily."

While more effort to implement (hopefully feasible..), this would let us keep hydration sync, avoid negative UX and have good performance.

I think we need to do some breaking changes to how hydration works in RQ and here I’ll try to outline why and the proposed changes. It is very technical and primarily targeted at maintainers and contributors to React Query, but I wanted to put the discussion in the open and outside feedback is very welcome! 😃

Whatever we land on, it will be documented clearly in a migration guide so no need to worry about this yet if you are a user of React Query.

The first reason we want to change hydration is because of changes in React 18. To support concurrent features and progressive/selective markup hydration, RQ is moving to use useSyncExternalStore, which requires us to make a bunch of behind the scene changes around hydration which in the end will affect the external API. I’ll describe this under initial hydration.

The second reason is that we are currently hydrating inside of render, and not in a useEffect. This was done for a bunch of reasons to better support metaframeworks like Next.js, but I ultimately think this was a mistake (mine) and is likely to have more noticeable negative consequences with concurrent features. I’ll describe this under progressive hydration.

Goal

To be clear, I don’t think we should be aiming to support streaming rendering initially. Data fetching with Suspense on the server wont be officially supported in the initial React 18 release and while technically possible, it’s a whole different beast to tackle. Instead the goal is to:

• Support the case where all data is available before you start hydrating markup on the client
• Support progressive/selective markup hydration (for example when using Suspense for code splitting, which IS supported initially)
• Support safely adding data to the cache after initial render, such as on page navigation (like when you want to add data prefetched in Next.js getServerSideProps)

Initial hydration

Initial hydration is a matter of answering the question:

If we render an app on the server with certain data in the RQ cache, how do we get that data into the cache before hydrating the markup on the client, so the resulting markup matches?

This has been relatively straightforward previously because markup hydration always happened in one synchronous operation, there was no chance for the data to change from when rendering started to when it finished.

In React 18, markup hydration can happen in asynchronous chunks (each Suspense boundary by itself). Between one part of the application hydrating and another, the cache might have changed, which could lead to markup mismatches between what was rendered on the server, and hydrated on the client.

Thankfully, useSyncExternalStore makes this relatively easy to deal with. It’s third argument takes a getServerSnapshot callback and the result of that callback is used as the state for hydration. So to support progressive/selective hydration in React 18 we need to:

• Capture an immutable snapshot of the initial cache provided by the server render
• Make that snapshot available everywhere RQ uses the uSES hook behind the scenes and pass it in there
• The above by itself doesn’t put the data into the RQ cache, so we also need to prime the cache with the initial data

I think the most straightforward API for this is that if you use SSR, we require you to pass in what is called the dehydratedState in the docs directly when you create the QueryClient. Perhaps something like:

const queryClient = new QueryClient({
  initialCache: dehydratedState
})

That way we can prime the cache initially so data is already there, and we can take care of capturing a snapshot of that and provide it to uSES behind the scenes.

This is how the hydration API was designed initially, but this was changed to provide it as a separate entrypoint instead. Now hydration is part of core so I think this approach makes a lot of sense.

If all you are doing is hydrating initial data from the server, and don't use anything like getServerSideProps, you could go ahead and remove all calls to useHydrate and just pass it in initially and everything would work.

An alternative could be that the user provided it to a context provider instead, but I think this makes for a less straightforward API.

Progressive hydration

This one is trickier. It is a matter of answering the question:

If we have some previously dehydrated cache data, how do we add that to an existing cache?

There are a few cases we want to support (might be more):

• Hydrating data from the server on page navigation (that is, support things like getServerSideProps in Next.js, or loaders in Remix)
• Hydrating data from other external sources, like localstorage, or say you use RQ inside a service worker and want to hydrate from that

For "other external sources", hydrating in a useEffect makes sense and has no negative tradeoffs. When the effect runs, data is added to the cache, which triggers rerenders in any components listening.

For data from the server on page navigation however, there are downsides to doing it in useEffect. Because that happens after render, data wont be available in that first render, forcing us to show a loading state before the hydration happens and we can render the real thing, even though we already have the data we need. This can also lead to unnecessarily tearing down existing components and rendering them again, losing state etc (see for example this related issue in next-redux-wrapper). This is why it is currently done in render.

The optimal place to hydrate extra data from the server into the cache in metaframeworks would be in some lifecycle before the framework kicks off rendering the next page. Something like receiveServerProps or the like, but no frameworks currently supports this. See related discussion in Next.js.

Even though doing it in a useEffect has negative downsides, I think with concurrent features that's a better option than keeping it inside of render. This is more "correct" and definitely more future proof. Even without concurrent features, I think we might have edge cases with this today.

Possible alternative

The only way to safely pass something to deep children inside of render itself is putting that thing on a React context via a Provider. A possible way to get around both hydrating in render and the negative downsides of useEffect could be to in addition to hydrating in useEffect also pass down the dehydratedState on a context (the provider for this could also be the one to call useEffect behind the scenes). If some dehydratedState lives on that context, on cache read we merge that temporarily (without writing it to the cache) the same way we do when hydrating, and when the useEffect has happened, we remove it from the context since now it's already in the cache.

I think this would work with concurrent features (nothing is written to the cache until useEffect) and avoid the downsides of doing it only in useEffect (like unnecessary loading states, fresh data is available directly on the first render).

This puts a lot of implementation burden and complexity on RQ though, for something that is a problem for many external stores (like Redux just as an example, next-redux-wrapper faces the same problem as mentioned in the issue linked earlier).

Because of all the tradeoffs mentioned here I'm less certain about the best solution for progressive hydration, but I think we should move useHydrate to useEffect and take it from there.

Since the low level imperative API hydrate() exists, users that want to keep the old behaviour of hydrating in render could create their own useHydrate-hook with the old behaviour (which we could document in a migration guide).

A note on Suspense

I think RQ in it's current form could be compatible with Suspense SSR as long as you don't do streaming, but more experimentation is needed.

If you use Suspense for data fetching and reading, I think it makes sense to also hydrate with Suspense. That is, you throw a synchronous thenable (kind of an "immediate Promise") which adds the data to the cache and resolves any queries currently waiting on that data. If this happens during the current render, it will rerender immediately and never show any fallback (behaviour documented in this test in React). I thought about possibly always using Suspense for hydration, but I think that will lead to problems (tearing and worse) when the data fetching itself is not Suspense based. Think about the case where a render is concurrent, we add data to our cache inside of Suspense and then that render aborts. The data is now in the cache and all queries currently listening to that data will have updated early.

A note on streaming and Server Components

I'll just note that this has some overlap with progressive hydration described above, but with a bunch of added complexity.

This is a good discussion on this. Also, this post in the React Working Group has some interesting notes under the header "Hydration Data".

I'm looking forward to see what the React team comes up with here, but there is nothing stopping us from experimenting with this ourselves after the initial release to support React 18.

Summary of proposed API changes

• We add initialCache (or similar) as an option when creating a new QueryClient(). This is required to pass in when using SSR, you can not use only useHydrate() as before.
• We move useHydrate() from happening in render to happen in an effect. This doesn't change the external API, but is a breaking behavioural change.

[bennettdams]

I can't give feedback to most of your post, but I would like to give some for one topic: The proposed API for initialCache.
There's one thing where I'm not sure that this API is not limiting: When you prefill the dehydrated state for more than one query in one server-side operation.
Right now, when I fetch data in getServerSideProps or getStaticProps, I sometimes are able to prefill another query with (a subset) of my data. Something like:

// inside getServerSideProps / getStaticProps

const dogIdToFetch = "dog-id-1"
const dogFetched = await fetchDog(dogIdToFetch)

const queryClient = new QueryClient();

// "dog" query
await queryClient.setQueryData(
  ["dog", dogIdToFetch],
  dogFetched
);

// the data for the dog could be used in some more detailed query, like "poodle"
if (dogFetched) {
  // "poodle" query
  await queryClient.setQueryData(
    ["poodle", dogIdToFetch],
    dogFetched
  );
}

This happens before dehydration with the current API, so a user is free to prefill queries as much as he wants.

[Ephem]

Great feedback, thank you!

initialCache will only be used for the very first React hydration of the markup passed from the server. At this point, the cache needs to be identical to what was used to render the markup on the server, or else we risk getting markup hydration mismatches which React doesn't like. This is the reason I think it makes sense to provide it directly to new QueryClient({ initialCache }), because the alternative of putting it on the provider instead could be confusing, consider this:

<QueryClientProvider queryClient={queryClient} initialCache={dehydratedState}>

What happens with the above if dehydratedState changes values, for example on a page transition? It's easy to think it gets hydrated but the idea is that it wont be, it's only used for the very initial value of the cache, which is what we need to pass on to uSES.

There are two aspects to consider here that makes me think this API will still work:

• It looks like the code example you posted runs inside getServerSideProps or getStaticProps? If so that will modify the cache before it gets dehydrated to the client. In that case, that prefilled data will already be included in the initialCache used to create the QueryClient, so the code you posted will run fine! 😃
• useHydrate is still a thing! It won't be needed on the very first page render (but won't hurt if it runs with the same data as in initialCache, or even some extra data), but for page navigations this will still be the mechanism used for hydration, but will now run in a useEffect instead of directly in render. This is what will make sure the code you posted works even on page transitions (but it might now trigger a very quick loading state when switching pages).

Does that seem reasonable?

[bennettdams]

Thanks!

It looks like the code example you posted runs inside getServerSideProps or getStaticProps

Yes, updated my post.

Maybe I understood you wrongly in your initial post, but you said

we require you to pass in what is called the dehydratedState in the docs directly when you create the QueryClient.

...which means that you need your dehydrated state before you create your QueryClient, right?

If that's the case, how does one prefill queries? For example, setQueryData always needs an existing QueryClient. That's what I meant with

This happens before dehydration with the current API

...where you already have an existing QueryClient that you can use. With the initialCache proposal, you don't have one to do that.

[Ephem]

Sorry for the late answer, I was sure I had already replied.. 🤦

You only need to initialize the cache with an initialCache if you intend to use it for rendering (or hydrating on the client really). The cache inside gSSP/gSP doesn't need this, so you can prefill however you want there (queryClient.fetchQuery and queryClient.setData both work). After that cache is primed fully with all the data you need, you dehydrate that, pass it to the rendering part of the application (remember, with Next and usually any SSR solution, you'll be using two caches even on the server, one cache for prefetching and separate one for rendering). In the rendering part of the application, you pass the dehydratedState into initialCache.

Does that make things any clearer? This is tricky stuff to both think about and explain. 😅

[TkDodo]

Great analysis, thank you 🙇 .

Hydrating data from other external sources, like localstorage, or say you use RQ inside a service worker and want to hydrate from that

I'd like to focus on this aspect specifically, as we have the persistQueryClient plugin that also attempts to restore your store (e.g. localStorage or asyncStorage) when the page loads. However, that plugin is always async. persistQueryClientRestore is what we'd want to run on page load (api slightly changed for v4):

https://github.com/tannerlinsley/react-query/blob/1abb3714637c3f9044a4294cc737cc41966a2f49/src/persistQueryClient/index.ts#L62-L68

and then create a subscription that syncs the store to the external storage.

This plugin uses hydrate under the hood already. Because it's async though, we run into race conditions, especially in react 18. see:

• persistQueryClient issues due to asynchronism #3245

Mainly because we don't block / defer rendering of the app while we are still restoring from the external store.