react-selective-hydration

SKILL.md

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 Suspense boundaries to delineate independently hydratable chunks of UI

Use renderToPipeableStream (Node) or renderToReadableStream (edge) for streaming SSR

Place heavy data-fetching components inside Suspense so 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