Keeping browser interactive during hydration

[ad1992]

Thank you for creating an awesome post on Suspense SSR Architecture 💯 🎉
As mentioned in Suspense SSR Architecture

In React 18, hydrating content inside Suspense boundaries happens with tiny gaps in which the browser can handle events. Thanks to this, the click is handled immediately, and the browser doesn’t appear stuck during long hydration on a low-end device. For example, this lets the user navigate away from the page they’re no longer interested in.

How do you make sure that the browser is still interactive during hydration? Is it like doing hydration in batches at some intervals?

Additionally, how would the below scenario get handled?

1. Let's say we have a component A (hydrated so clickable now) and a component B which is still hydrating (both are siblings).
   Clicking on component A updates some state X which B is subscribed (an external store) to as well so If the user clicks on comp A. and B is still hydrating so what will happen in this case ? will React not dispatch the event until B is hydrated?
2. What if A and B are not siblings?

[gaearon]

Thanks for the question!

While your question is specifically about the hydration, I wanted to address the more general question of "how do you keep the browser interactive" since the answer is the same for multiple features.

So I'll split my answer into:

• How can React keep the browser responsive?
• What happens when you set parent state before a sibling gets hydrated?

How can React keep the browser responsive?

Conceptually, you can think of React rendering algorithm like this:

while (hasMoreComponents) {
  renderNextComponent()
}

(Source code)

Here, "render" means calling your component function and putting DOM changes into a queue. When we run out of components (when we've walked the entire tree affected by a state update), we actually update the DOM.

This is a synchronous render.

In React 18, we have a new concept of "concurrent" renders. They look more like this:

while (hasMoreComponents && !hasOtherStuffToDo) {
  renderNextComponent()
}

(Source code)

The new thing is that between each call to a component function, we check if we have something more important to do. We'd periodically set this flag to true to let the browser handle events and paint the screen if needed. Then, if we have nothing more urgent to do, we get back into this loop and do a bit more rendering. In other words, concurrent renders are interruptible. For example, if during a gap, you set the state again, we won't attempt to finish the stale render. We'll start from scratch.

(Note: the reality is a bit more nuanced but this is a decent approximation.)

By default, we use the first (non-interruptible) algorithm. The second (interruptible) algorithm kicks in for:

• Updates from startTransition (which is the main opt-in mechanism to this feature, to be documented soon)
• Retries from <Suspense> (which is what happens during hydration of a <Suspense> boundary!)
• Some other cases we'll document

So this is how it works. We can't "pause" or "interrupt" JS code that already executes. That's not possible. But we can choose to stop a render pass and do something else instead (e.g. render another update or let the browser paint) before calling the next component.

In React, each individual component usually takes very little time to render (< 1 ms). This is because component's rendering time does not include its children. JSX is lazy, so <Button /> does not call Button like Button() call would. So even if you have a pretty heavy tree, each individual layer in it is small enough. This is why, even though React can't stop the code that already executes, in practice it feels like it's interruptible. And being interruptible is what allows the browser to handle events in between.

This was a general answer about how it's possible for React to interrupt execution. Now onto your more specific question.

What happens when you set parent state before a sibling gets hydrated?

Let's say we have a component A (hydrated so clickable now) and a component B which is still hydrating (both are siblings).

I should clarify that granularity of hydration is determined by the <Suspense> boundaries rather than individual components. So even though React calls your components one by one, it will not hydrate them in isolation. You can think of it as hydrating in "levels". A single "level" starts at a Suspense boundary and includes all components in it (except the ones that are also wrapped in Suspense — which become the next "level"). A "level" is not a technical concept, it's only a metaphor I'm using here.

So coming back to your question, let's say you're speaking about subtrees of A and B rather than individual components A and B.

Clicking on component A updates some state X which B is subscribed to as well so If the user clicks on comp A. and B is still hydrating so what will happen in this case ? will React not dispatch the event until B is hydrated?

If component A updates its own state X, then it won't affect B since B is not a child of A.

If component A updates a parent state X, what happens depends on where the component B is:

1. If B is really A's sibling, this means it's within the same closest Suspense boundary as A. In this case there is no special behavior. This is because components within the same closest Suspense boundary always get their event handlers attached together. So either they're both not hydrated (and event gets queued until they are), or they're both hydrated, and the event is handled immediately. This is similar to how other DOM changes work: React walks the components one by one, but it updates the DOM in batches (we call them "commits"). For hydration, committing means attaching the event handlers.

2. If B is not a direct A's sibling, but something like <A /> <Suspense fallback={<Spinner />}><B /></Suspense>, A updates some state above both, and B is not hydrated yet, things get more interesting. Let's use an example. We may have a situation where we have some HTML from the server (e.g. a comment section) that has not yet been hydrated. And then you do an update above it (e.g. use a Dark More switch). In this case React will have to replace the server HTML with the Suspense fallback. This is because it's stale. For example, you wouldn't want to see comments using a Light theme after you have already switched it to Dark. In general, this means that top-level updates during the app startup, especially updating context, are not ideal. They force the user to see more fallbacks. However, if you can "prove" to React that some update doesn't affect a subtree — for example, if you don't change top-level context during load and also put a memo() somewhere above the B tree — then React can keep the server content there. Because it knows this is safe.

[marcysutton]

This is a helpful explanation! It's also gotten me thinking about what happens with the user's keyboard focus if a part of the page is re-rendered. Have you run into issues with having to put focus back into re-rendered content, or on a spinner, so focus isn't lost?

[sebmarkbage]

@marcysutton During hydration this is generally not an issue because we hydrate first, by reusing the DOM which preserves focus and then apply the update after. This ensures that the same thing happens as on the client. We also hydrate parents first so if there's logic to "catch" the focus in a parent when a child is lost, then that client-side code is able to handle that.

The selective hydration also prioritizes the thing that gets focus or blur so that client code that does handle this scenario is able to take over focus control as soon as possible.

So it's no different from how we'd handle it on the client.

However, that general problem space of redirecting focus when it's lost is still a research space and we think we can build even better APIs around it. We have an experiment in the repo called Scopes that is the first step to try to tackle some of that. We also have some user space code at Facebook that deals with this general concept.

Setting focus on a fallback before it loads and then redirecting it to the main content once it loads is one such scenario.

[trueadm]

I can comment more on Scopes, which are an experimental API that we use internally at Facebook. All our focus management and logic around that relies on Scopes. Scopes have two key features: being able to "query" the host components of the children of a Scope, and also being able to query child React context providers.

We have user-land components that leverage Scopes, keeping Scopes as more of an implementation detail. These are components such as <FocusWithinHandler>, <FocusRegion>, <FocusTable> etc.

The key one that you allude to is what we use FocusRegion for. When you wrap this component around a sub-tree, it listens to when focus is lost because of Suspense or because a user-action caused the active element to be detached. Rather than let focus move to the document body, we attempt to "recover" focus to a nearby node that is best suited. FocusRegion takes a prop that lets the user specify the query for what node should be recovered to. In most cases, we want to query the nearest DOM node that is tab focusable and visible, sometimes we might want focus to move to a heading (h2 etc) instead. FocusRegion also handles other focus management responsibilities, like focus containment, auto focus, focus restoration (for stacked FocusRegions) and other things that make the AX better on the web.

Hope that explains things a bit better. Please note, that the APIs mentioned above are all experimental and are not final.

[sebmarkbage]

If the update is fully within plain React patterns like calling setState or dispatch in a callback that updates a parent and passes it down, then what @gaearon said in the last scenario applies.

However, @ad1992's question mentioned "subscribed". I suspect what is meant by that is something like a Flux-like subscription to an external store with short cuts to the tree.

In that scenario where they're in separate Suspense boundaries it is possible for the tree to become inconsistent until it's fully hydrated. Because B won't be subscribed yet it won't know we have to update it and React doesn't know it'll eventually be there. So A updates but not yet B.

However, there's another subtle scenario in this case where if React now tries to hydrate B, it can cause a hydration error if it reads from the external Flux store since it has changed. This is one of the concurrency scenarios that a new API called useMutableSource tries to address. Basically, we'd likely have to throw away the rendered HTML for B in this scenario and rerender it on the client. But we have to know that we should. useMutableSource lets us know whether a Flux store has changed since we started hydrating it. We also need to know about these at the root level when we start hydrating using external stores.

[ad1992]

Thank you for the detailed answers @gaearon @sebmarkbage!

However, @ad1992's question mentioned "subscribed". I suspect what is meant by that is something like a Flux-like subscription to an external store with short cuts to the tree.

Yes, that's right I meant external store (Edited the question to make it more clear).

So if A and B are using an external store and opt-in for suspense API, then useMutableSource will be definitely needed right? I am sure you will be covering useMutableSource in a different post but to just get an idea of how it will work, will it be some kind of hook which will be working out of the box with external stores (external stores will use the hook internally) or will it be where the host has to create a kind of wrapper with the hook to listen to external stores?

[sebmarkbage]

There's an existing RFC that describes some of the other motivations and the API. reactjs/rfcs#147

[ad1992]

Thanks for sharing the RFC @sebmarkbage 👍🏻.
Is this in the plan for react 18 release?
Since there is a chance that tree can become inconsistent until hydrated when using external store so does that mean the production apps using an external store might not be able to opt-in suspense?

[sebmarkbage]

I'd expect to at least be in a fast follow 18.x minor release.

However, as with all these issues, it won't necessarily happen and cause problems in practice. In fact, we have one of these issues at Facebook and it did come up as a production bug and we worked around it in one place. It could come up again but in practice it doesn't happen often. It might not happen to you. So I wouldn't be too worried about it neither.

[ad1992]

Got it, thanks for clarifying 👍🏻