New in 18: Selective Hydration

[salazarm]

Selective Hydration

As mentioned in #37, React 18 will include Selective Hydration as part of our new Streaming architecture.

As a reminder hydration is primarily for attaching event handlers and preparing to respond to those events. It's also secondarily to enhance what's already on the server rendered page - for example auto-playing videos, or starting subscriptions to live data like like-count. The goal of Selective Hydration is to prioritize the order of this progressive enhancement based off what users interact with. Previously hydration required all of the code to be downloaded and ran before we could respond to user interactions. With our new streaming architecture we can instead progressively enhance sections of a React application allowing us to respond to user interactions sooner. Absent any user interaction we also progressively hydrate during idle cycles.

How does it work?

• Initially Suspense boundaries are not hydrated.
• Discrete events (eg. click/keypresses) trigger synchronous (selective) hydration in the capture phase if the code in its encapsulating Suspense boundary is ready.
  • If the event can't be synchronously hydrated then we'll increase the priority of that boundary so it hydrates first when it's ready.
• Hovered or focused Suspense boundaries get increased hydration priority but are not synchronously hydrated. Persistent events (focusin, mouseenter, dragenter, mouseover, pointerover, gotpointercapture) will be rebroadcasted on hydration.
  • Only the last event of each type will be rebroadcasted (think of it as being informed on what the current state of the world is. eg what the current focused/hovered target is.)
  • Events are rebroadcasted using native event.dispatch.
  • This means native event handlers, stopPropagation, and capture phases will all work like normal.
• If the html can’t be hydrated or if its a persistent event then we will call stopPropagation() on the event
  • This is to prevent an event that would have had stopPropagation or preventDefault called on it in user space from bubbling up (eg: submitting a form).
• unstable_scheduleHydration allows you to increase the hydration priority of a Suspense boundary.
• In idle cycles, any remaining Suspense boundaries are hydrated asynchronously.
  • Breaking up the hydration into idle cycles keeps the page responsive.

For example consider the following app.

<Layout>
  <NavBar />
  <Suspense fallback={<Spinner />}>
    <Sidebar />
  </Suspense>
  <RightPane>
    <Post />
    <Suspense fallback={<Spinner />}>
      <Comments />
    </Suspense>
  </RightPane>
</Layout>

Suppose the app is not yet hydrated but all of the code is downloaded. If the user clicks on the dehydrated Comments component, then, in the capture phase, React will synchronously hydrate the Suspense boundary containing the Comments components (and its parent suspense boundary if it's not already hydrated), and the event will continue normally as if it was already hydrated. This means the Sidebar will remain dehydrated since its at a lower priority.

If the code is not yet downloaded then React will call stopPropagation() and increase the priority of the Comments boundary so that when its code is downloaded and ready the Comments Suspense boundary will be hydrated before the Sidebar Suspense boundary.