Add DevTools visualization for SSR hydration

[bvaughn]

This feature relates to several new React APIs: concurrent mode, suspense, and server rendering / hydration

Background info

When hydrating server-rendered content, React starts working on the outermost Suspense boundary and works its way in. During hydration, the server rendered HTML isn't interactive. React records events to replay them once content becomes interactive- (but that doesn't actually happen until React finishes work on the nearest boundary and commits it). React may also reprioritize the order in which boundaries are processed (so that boundaries with pending events get processed sooner).

This general process can be hard to reason about and debug, because much of it is not observable visually (beyond some interactions potentially feeling more laggy than expected).

DevTools already provides some visual overlays (e.g. which elements were rendered by the currently selected Component, "highlight updates"). Perhaps DevTools could help here too by visualizing which boundaries in the tree have been hydrated.

Visualizing hydration progress

1. When React begins hydrating a new root¹ DevTools will show a visual overlay² that covers the entire DOM element container.
2. As React hydrates and commits each new level of Suspense boundaries, DevTools will draw the overlay to only cover the not-yet-hydrated boundaries.
3. Once hydration is completed, all overlays will be cleared³.

This feature would be opt-in via a new DevTools setting.

¹ This suggests a new React-to-DevTools hook to inform DevTools when hydration starts.

² This overlay would nee to be designed. Perhaps some combination of semi-transparent with stripes or bars so that it is high contrast enough to be seen.

³ Because the data required to draw these overlays is essentially just a timestamp and a set of rects, some form of replay might be a nice addition.

Special cases

It could be helpful to highlight a couple of special cases by temporarily showing a different style overlay:

• Client rendered content inside of a server rendered fallback. (This case.) In some cases, the server rendered content may be a forced fallback that gets filled in with client rendered content.
• React can't complete hydration fast enough to process a client-side update. (This case.) In this case, React ends up deleting the server-rendered content and replacing it with client rendered content. For example, a layout effect may set state on an ancestor that updates context. This update is synchronous (because it comes from within a layout effect) so it immediately expires.

I don't know if the above cases can be reliably detected by DevTools at present. They may require additional information (or an additional React-to-DevTools hook).

The following case does not need to be highlighted because it is not a deopt:

• Server rendered content removed before hydration. In some cases, server rendered content is thrown away before hydration completes because of a user interaction. For example, if the user navigates to a new page before the initial page has finished hydrating.

[GiancarlosIO]

👀

[sandeepkumar03]

2024, still an issue debugging hydration errors.