How it works
Server. react-dom/server is React's Fizz renderer. It renders components to HTML segments, not fibers: no DOM, no commit phase, so no Effects. Two adjacent text nodes need a separator so the client can find both: Clicked {count} became Clicked <!-- -->0. Suspense boundaries are wrapped in comment markers (<!--$--> … <!--/$--> in 19.3.1) that tell the client where a boundary starts and ends.
Client. From React 19.3.1's ReactDOMRoot.js and ReactFiberHydrationContext.js (implementation details):
hydrateRoot attaches React's event listeners to the container, as createRoot does, then schedules the initial render on a hydration lane. It returns before rendering: a log right after the call printed before render on client.
- The render is an ordinary render with a cursor into the existing DOM. For each host fiber,
tryToClaimNextHydratableInstance checks whether the next DOM node has the same tag (canHydrateInstance). If it does, the fiber's stateNode becomes that node; otherwise it's a mismatch.
hydrateInstance links the node to its fiber and stores the props, which is where the event system later finds onClick. Text is compared to the server text.
- The commit inserts nothing new; it attaches refs and runs layout effects, then passive Effects.
// What hydration does per element, simplified from ReactFiberConfigDOM.js
function hydrateInstance(domNode, type, props, fiber) {
precacheFiberNode(fiber, domNode); // domNode → fiber, for events
updateFiberProps(domNode, props); // where onClick is read on dispatch
return hydrateProperties(domNode, type, props); // false → text mismatch
}
Edge cases
What React 19.3.1 exports (checked by importing in Node 24):
renderToString with a pending use inside <Suspense> didn't throw. It emitted the fallback inside a client-rendered boundary marker:
<div><i>1</i><!--$!--><template></template><p>Loading</p><!--/$--></div>
That's the production build; development also puts the reason, "The server used "renderToString" which does not support Suspense…", in the template's data-msg.
prerender on the same tree waited and emitted <!--$--><b>data</b><!--/$-->. Neither ran the component's Effects or ref callback; its useState initializer ran once per render.
Strict Mode: since React 19.3 it double-invokes Effects during hydration too, as with createRoot. In the test (development, Chrome 156 and Firefox 159), the component rendered twice and ran its layout effect and Effect twice, while keeping the server node.
Real-world scenario
A product page served by Node. The server fetches the product, renders the page with renderToPipeableStream, and pipes in onShellReady with status 200; onShellError sends a 500 page. The browser paints the title, price and image from HTML, so the content is visible before the bundle downloads. Reviews sit in a <Suspense> boundary and stream later. When client.js runs, hydrateRoot(document, <App />) attaches the Add to cart handler to the existing button. The data the server used must reach the client too, usually serialized into the HTML by the framework, or the client's first render would differ.
Trade-offs
Server rendering improves first paint and makes content visible to crawlers and users on slow devices. It doesn't reduce the JavaScript: the client still downloads and runs every component to hydrate it, so time to interactive can be later than with a client-only app, and the page looks clickable before it is. It also needs a server or a build step, and every component must render the same in both environments. Server Components go further by keeping some components off the client entirely.