External store state hydration

[Ephem]

This subject has been touched upon in other places of this working group, in the discussion about useSyncExternalStore (and specifically the getServerSnapshot argument), as well as in the Library Update Guide: <script> under the header "Hydration Data".

Since this is an important subject for most/all external stores that want to support SSR I wanted to pull together a quick summary to verify that I've understood things correctly.

Since the initial React 18 release wont have official support for Suspense data fetching, I'll only talk about the case where you have all data available up front on the client, not streaming data hydration (the above Library guide has some great notes on that though).

Background

State affects markup, and because markup has to be equal when rendering on the server and hydrating that markup on the client, we have to start with identical state in both cases. The normal way to do this is to embed the state used on the server in the markup, and prime the external store with that.

The thing that changes in React 18 is that markup hydration can now be "async" (if <Suspense> is used) and because state might update in between chunks of markup hydration, we need some way to guarantee the hydration process always reads the initial external store state to avoid hydration mismatches.

Solution

The new useSyncExternalStore hook has a third argument, called getServerSnapshot. This will always be used to read data from the store when React is hydrating markup, so if we pass in a callback that returns a frozen/immutable version of the initial store state there, we will avoid markup hydration mismatches, even if state changes during hydration. If state has changed, React will immediately rerender with the new state, so while UI might get temporarily inconsistent during hydration, it will always end up in a consistent state(?).

When to add data to/hydrate the actual store

As long as we don't use Suspense data fetching, all data still needs to be fetched up front on the server, before rendering. This means it can always be available before hydrating on the client, so the recommended way to hydrate the external store is to do that when creating the store.

A caveat is that in some metaframeworks, there is no way for developers to ergonomically run code before hydration starts, in which case the external store needs to be created inside of render. This should be fine, at least if store creation has no observable side effects, since nothing is subscribing to the store at this point?

In essence, would something like this be fine for store creation?

export default function MyApp({ Component, pageProps }) {
  const [externalStore] = React.useState(() => new ExternalStore({
    initialState: pageProps.dehydratedStateFromServer
  }))

  return (
    <ExternalStoreProvider store={externalStore}>
      <Component />
    </ExternalStoreProvider>
  )
}

Behind the scenes, this external store should grab a frozen copy of the initialState and pass that down to anywhere it uses the uSES to read data from the store, so it can be passed in (in callback form) to the third argument getServerSnapshot.

Is this correct, am I missing something? Is there any extra nuance/edge cases to be aware of?

[Ephem]

Bonus: "Incremental" external store hydration

Since this is not directly related to React 18 I was hesitant at first to post it here in the working group, but since it's a common problem related to external store hydration, might have different tradeoffs in React 18 and kind of foreshadows a similar challenge with Server Components, I thought I'd at least describe the challenge and see if anyone has immediate advice. Sorry if the WG is the wrong place for this!

A problem related to SSR hydration, but with a whole different set of challenges is how external stores can support metaframeworks that provide capability to abstract data fetching to the server, even on client side navigations. Next.js getServerSideProps/getStaticProps and Remix loaders are current examples of this (Server Components being a similar future one).

In this case, we don't have anything equal to getServerSnapshot that works during the first render of the new route in the client, and no way to run code before the render happens, so we seemingly have two options:

• Hydrate data to the store directly in the render phase, so it's available to child components immediately
• Hydrate data in a useEffect, which means that we have to delay rendering the route even if we already have access to the data

The first one is common today in React 17. The most popular Redux wrapper for Next.js hydrates in a constructor/shouldComponentUpdate and React Query does it in render (I wrote the RQ one btw so I don't mean to shame, just point to current tradeoffs!). While a common approach, this is an unsafe side effect in the render phase since at this point we might have listeners for that data. This might well lead to edge cases already and these might get more common in 18(?).

The second option requires us to stay in a loading state unnecessarily, and possibly switch to a separate loading state from what the metaframeworks themselves provide, which leads to a less than optimal UX even if very quick. It can also have the drawback of loosing state in components that would otherwise stay on screen.

(There might be a third option, keep the store state on a context instead, since a modified context can be passed down safely inside of render. That has other problems though and besides, then the store wouldn't really be "external" anymore. A variant of this might be to keep only the "new" data on a context until an effect can hydrate it properly?)

If anyone has any good ideas or advice on how to tackle this I'd be really grateful! (Feels dirty and wrong, but is this that elusive case where a useIsomorphicLayoutEffect might be an okayish solution after all, since it only happens on the client and this needs to rerender anyway..? 😇)

For now the working hypothesis is to switch React Query from hydrating in render to in useEffect in these cases, as per this writeup. Though it has some downsides, this seems like the safer option.

[sebmarkbage]

In general spawning things from useEffect like secondary render passes is not great. We've actually considered just making it a warning because it's such a common source of perf problems. Not only can it cause multiple passes over the same content or even infinite loops. It causes multiple layout passes from the browser. If you are currently in a startTransition, it can't combine it into one render so if something else on the page suspense as a result of the second useEffect it must trigger a loading state instead of showing old data. So if that was a "refresh" it breaks the experience.

That said, one of the downsides of using a synchronous external store is that it can trigger this scenario anyway just by having mutable data. It can be completely avoided by just not using an external mutable store. So you're in this middle ground that isn't completely idiomatic regardless. I'll continue assuming you're not willing to give up other benefits of an external mutable store though.

There are kind of two cases, one case is for components you've already rendered past by the time you find the one adding new data. Those will still use stale data. Things below the thing adding data as a side-effect can observe newer data.

One approach, which is the direction the built-in React <Cache> is going is that those remain inconsistent when your "refetch" is lower in the tree. That also supports Server Components where you don't want to refetch all Server Components anytime you invalidate or navigate on the page. Since there's no normalization client side for Server Components, you end up with the scenario where you can see inconsistent data in different parts of the tree. That inconsistency is a feature though because at least it's at predictable bounds.

What you typically want to achieve from an external store is to update other parts of the page with whatever data was new in this page to achieve consistency. Although that's kind of a lie too because it's only consistent if you fetched all the same data that was in the original queries and anything downstream of those because otherwise you can hit the parent-child problem (where there is a logical inconsistency because they didn't fetch at the same time). So whatever you put in the store might not actually be consistent.

However, assuming your store actually end up with logically consistent data, useSyncExternalStore will at least ensure that all data is up-to-date by updating them synchronously at the end of the render. That has some of the issues mentioned above. It also forces you to update everything at once which can slow down the display of the most important content that you requested.

Therefore, my personal favorite approach to this problem is to use the "new" data directly from the "server" using a Context in the tree below where you got it (this is the "third option"), and then you update the store in something like useEffect(() => requestIdleCallback(...)) (or postTask). Although if you're ok with this consistency being a couple of frames behind, you might again want to reconsider if you really need an external store for this or if it could just be immutable data. You'll need some versioning or flag to determine which source to read from at each location though.

That's really at the core of this issue though. The reason side-effects in render are discouraged is that they're hard to predict but there's some of that even with effects.

If you did have a hook from the meta-framework, like Next.js, when it got data. If Next.js prefetched data, should that go into the store when that prefetch returns? If you start prefetching page C and in the meantime navigate to Page A and A completes first and then C, which data should win?

Similarly, the lack of side-effects in render helps React do prerendering of other pages, but should that prerendering override the data in the store? Moving the consistency layer to effects help make that a bit more predictable but it really depends on what your semantics should be.

[Ephem]

Thank you, this is very, very helpful! I've definitely failed to appreciate some of the ways prerendering plays into this, and especially how that future makes it not make sense for metaframeworks to support a lifecycle like that. 🙏

I'll continue assuming you're not willing to give up other benefits of an external mutable store though.

It's not so much that as it is that I'm working with libraries that are already pretty entrenched in that choice. 😃 I'm thinking about this a bit like Different levels of Concurrent Rendering support where it might not be possible to reach Level 3 with the current approach, but I'm focusing on making it work and making it right, even if that means deopting and less than optimal performance.

From that perspective, is this a fair interpretation of what you are saying for "incremental hydration"? (And is this also likely to hold true for hydrating data from streaming/RSCs in the future since it seems like a similar problem? No need to deep dive there though, I know it's something you are still working on.)

"Level 0" - Hydrate in render

Has always been discouraged and will lead to more problems with concurrent features. As you mentioned, it's easy to see how hydrating new data to a store during a prerender could lead to all kinds of problems. Same problem exists today, for example if a subtree throws an error after hydrating.

"Level 1" - Hydrate in useEffect

Will avoid straight up bugs and will be consistent since all UI updates trigger at the same time, but is discouraged because of a few reasons. Bad performance, showing loading states unnecessarily even if data is already available and also this basically opts out of prerendering since we could only prerender loading states even when data is available.

"Level 2" - Put the new data on a context to read from during render, later trigger hydrate in useEffect

The recommended approach for mutable external stores. This avoids the performance problems of "Level 1" and is compatible with prerendering. Different parts of the UI can be inconsistent temporarily if components outside of the context subtree are listening to data updated in the hydrate, since that happens later, but it will be eventually consistent.

"Level 3" - React State/Context(/Cache) or immutable versioned external stores(?)

Instead of having a single true source of state that gets updated in the commit phase, you have immutable versions and calculate and read the correct version in the correct render. This is kind of what React is doing behind the scenes (maybe I'm simplifying a lot here..), but could conceivably be implemented externally as well (though knowing which version to read could be a problem?).

I'm not sure I fully grasp the different tradeoffs and nuance between this and "Level 2" completely yet, but the idea here seems to be it would not update components outside of the subtree, instead opting for inconsistency at predictable bounds which will be extra important for example for avoiding refetching with RSCs?

(Note that I don't mean levels here to necessarily correspond to the ones in Concurrent Rendering support, and here each level isn't a straight up improvement on those below as they have slightly different tradeoffs)

[sebmarkbage]

To your original main question:

Behind the scenes, this external store should grab a frozen copy of the initialState and pass that down to anywhere it uses the uSES to read data from the store, so it can be passed in (in callback form) to the third argument getServerSnapshot.

Yes. I don't see a problem with it, other than maybe performance because that store might be recreated when something suspends at the root. Probably not a big deal.

[Ephem]

Thanks for verifying the approach, that's a good point about performance and especially recreation!

I realized I used grab a frozen copy a bit sloppily, grab an immutable/unchanging version or something is probably more precise. Best case a library treats state as immutable and can just keep a reference to the initial state, worst case you can deep copy to preserve. Good to know either way works.

[sebmarkbage]

As long as no other component writes to it, it should be fine. There's no side-effects then.

There's a variant of this with useRef already. That ref can be passed anywhere. React can't really just recompute the parent that created that ref without either reusing the state/refs or also recomputing the children that it might have been passed to.