patternsdev Selective Hydration
In previous articles, we covered how SSR with hydration can improve user experience. React is able to (quickly) generate a tree on the server using the renderToString method that the react-dom/server library provides, which gets sent to the client after the entire tree has been generated. The rendered HTML is non interactive, until the JavaScript bundle has been fetched and loaded, after which React walks down the tree to hydrate and attaches the handlers.
However, this approach can lead to some performance issues due to some limitations with the current implementation.
When to Use
- Use this when you want to make parts of your SSR page interactive before all JavaScript has loaded
- This is helpful when slow components (e.g., data-fetching components) are blocking the entire page's hydration
Instructions
- Use
Suspenseboundaries to delineate independently hydratable chunks of UI - Use
renderToPipeableStream(Node) orrenderToReadableStream(edge) for streaming SSR - Place heavy data-fetching components inside
Suspenseso they don't delay sibling hydration - Ensure critical interactive components are not inside long-lived loading fallbacks
- Use
hydrateRoot(React 18+) to benefit from selective hydration
Details
Before the server-rendered HTML tree is able to get sent to the client, all components need to be ready. This means that components that may rely on an external API call or any process that could cause some delays, might end up blocking smaller components from being rendered quickly.
Besides a slower tree generation, another issue is the fact that React only hydrates the tree once. This means that before React is able to hydrate any of the components, it needs to have fetched the JavaScript for all of the components before it's able to hydrate any of them. This means that smaller components (with smaller bundles) have to wait for the larger components's code to be fetched and loaded, until React is able to hydrate anything on your website. During this time, the website remained non-interactive.
React 18 solves these problems by allowing us to combine streaming server-side rendering with a new approach to hydration: Selective Hydration!
Instead of using renderToString, modern React SSR uses renderToPipeableStream() on Node runtimes or renderToReadableStream() on Web Stream runtimes.
These APIs, in combination with hydrateRoot() and Suspense, make it possible to start streaming HTML without having to wait for the larger components to be ready. This means that we can lazy-load components when using SSR without blocking the hydration of the rest of the page.
The Comments component, which earlier slowed down the tree generation and TTI, is now wrapped in Suspense. This tells React to not let this component slow down the rest of the tree generation. Instead, React inserts the fallback components as the initially rendered HTML, and continues to generate the rest of the tree before it's sent to the client.
In the meantime, we're still fetching the external data that we need for the Comments component.
Selective hydration makes it possible to already hydrate the components that were sent to the client, even before the Comments component has been sent!
Once the data for the Comments component is ready, React starts streaming the HTML for this component, as well as a small <script> to replace the fallback loader.
React starts the hydration after the new HTML has been injected.
React 18 fixes some issues that people often encountered when using SSR with React.
Streaming rendering allows you to start streaming components as soon as they're ready, without risking a slower FCP and TTI due to components that might take longer to generate on the server.
Components can be hydrated as soon as they're streamed to the client, since we no longer have to wait for all JavaScript to load to start hydrating and can start interacting with the app before all components have been hydrated.