Streaming SSR with Suspense

The plain-language idea

Classic server-side rendering builds the entire HTML string for a page, top to bottom, before sending anything to the browser. If one part of the page needs a slow database query, the whole response waits on it — a fast product title sits blocked behind a slow reviews list that hasn't loaded yet.

Streaming SSR breaks that dependency. You wrap the slow part in a Suspense boundary, and React sends the rest of the page — the "shell" — the instant it's ready, with a fallback placeholder sitting where the slow part will go. When the slow data resolves, React streams a small chunk of HTML and script that swaps the placeholder for the real content, in place, without the browser reloading anything.

See it in a real thing: a product page with slow reviews

import { renderToPipeableStream } from "react-dom/server";

function ProductPage() {
  return (
    <Layout>
      <ProductSummary />                 {/* fast — part of the shell */}
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews />                       {/* slow — streamed in later */}
      </Suspense>
    </Layout>
  );
}

renderToPipeableStream(<ProductPage />, {
  onShellReady() {
    response.statusCode = 200;
    response.setHeader("Content-Type", "text/html");
    pipe(response);
  },
});

onShellReady fires the moment everything outside a Suspense boundary is done rendering — ProductSummary and ReviewsSkeleton, not Reviews itself. The browser gets real, paintable HTML immediately and starts rendering the page while Reviews is still fetching on the server. Once that fetch resolves, React finishes rendering Reviews in the background and streams the result down the same connection as an out-of-order chunk; a small inline script relocates it into the skeleton's spot. No second request, no client-side refetch — the server just kept the connection open and sent more.

What people usually miss

Watch out

• The shell no longer waits for the slowest query — that's the entire point, and it's the opposite of the old getServerSideProps-style model where one slow call blocked the whole response, including parts that had nothing to do with it.
• Streaming doesn't remove the need for hydration. The streamed HTML is real markup and paints immediately, but it's inert until the client JS attaches event handlers — a fast shell that isn't hydrated yet still can't respond to clicks.
• Boundaries resolve in whatever order their data finishes, not top-to-bottom DOM order. A boundary lower on the page can fill in before one above it; visually, each fallback just sits in its own spot until its own data is ready, independent of the others.

The genealogy: the same Suspense, a server-side use

This is the same Suspense component this track's lazy-loading lesson uses to pause rendering for a component that isn't ready yet — streaming SSR is that identical mechanism applied on the server instead of the client, deciding what to send now versus later instead of what to render now versus later. What arrives from the server still has to become interactive the same way any server-rendered markup does, which is this track's hydration lesson.