Skip to content
Tutorials Center
My learning

Topics

React Reference ยท react-dom/server and Static APIs

Streaming server rendering with Suspense

How React streams HTML as data arrives: the shell, Suspense boundaries, out-of-order chunks, inline swap scripts, error fallbacks and selective hydration.

Streaming server rendering sends a page in pieces. Instead of waiting for the slowest query before writing a single byte, React writes the shell at once: everything that is ready, with a fallback in place of each Suspense boundary that still waits. When a boundary's data arrives, React writes the finished HTML for it later in the same response, together with a tiny script that moves it into position.

You do not write any of this machinery. You wrap the slow part in <Suspense fallback={...}>, let a component wait with use (or a framework data API), and call a streaming renderer: renderToPipeableStream on Node.js, renderToReadableStream elsewhere. The page appears quickly, and the browser hydrates finished parts without waiting for the rest.

Try it

Out-of-order delivery

Boundary A comes first in the page and B second, but B's data is ready first, so its block (S:1) is written before A's (S:0). The inline scripts put each block into the right placeholder, wherever it landed in the stream. The shell, at the top, has both fallbacks.

Nested boundaries and an error

The inner boundary cannot be sent before the outer one has content, because it lives inside it, so the outer block carries a placeholder for it. The broken widget does not stop the page: its boundary turns into <!--$!--> followed by the fallback, and onError receives the error once. On the client, React retries that boundary and shows the nearest error boundary if it fails again.

How the pieces fit

  1. The shell. React renders until it hits components that suspend. Each waiting Suspense boundary becomes <!--$?--><template id="B:n"></template>fallback<!--/$-->. Everything before and after is complete HTML.
  2. The flush. The renderer calls onShellReady (Node) or resolves the promise (web streams). You send headers and the first bytes.
  3. Completed boundaries. When data arrives, React writes <div hidden id="S:n">...</div> and a script that replaces the placeholder with it. Boundaries are sent in the order they finish, not the order in the page.
  4. Errors. A boundary that throws is marked with <!--$!-->. The server logs the error through onError; the client re-renders the boundary.
  5. Hydration. hydrateRoot hydrates each boundary separately. Parts that arrived get interactive first, and a click on a part that is still pending makes React prioritize it.

Usage notes

  • Choose boundaries by importance. Content that search engines or users need at once belongs in the shell, outside a boundary, or behind an onAllReady wait for bots.
  • Boundaries are the unit of reveal. One slow query inside a large boundary delays everything in it. Smaller boundaries stream earlier but add more placeholder markup.
  • Status and headers are fixed at the first byte. A failure in a boundary after that cannot change the HTTP status. Decide what must be right before the shell.
  • The client needs the same tree. Fallbacks and finished content are both valid hydration input; a different tree structure still causes a mismatch.
  • Buffering proxies break it. Compression middleware or a CDN rule that buffers the response hides the progressive output. Flush after each chunk and test with the real stack in front.
  • Timeouts. Pass an AbortSignal (web streams) or call abort() (Node) so a hung promise cannot hold the connection open; unfinished boundaries then render on the client.
  • renderToString does not stream and does not wait; a suspended boundary there becomes its fallback plus a client-render marker.
  • Static output can wait for all data instead: see prerender.