Streaming server rendering

A product page that arrives in pieces

In Server rendering and hydration, the server called renderToString and sent the whole page at once. That's fine while every part is quick. But a real product page waits for data: the details from one service, the reviews from another. renderToString can't wait, so it sends fallbacks, and prerender waits for everything, so one slow service holds up the whole page.

Streaming, which Rendering strategies showed in a list of chunks, does better than both. The server sends what's ready at once, with a Suspense fallback where each slow part goes, and keeps the response open. As each part's data arrives, it sends that part's HTML down the same response, and the browser puts it in place. Here is a Node.js server that streams a tea shop's product page. It runs on a server, so it has no result here:

import { createServer } from "node:http";
import { renderToPipeableStream } from "react-dom/server";
import Document from "./Document.jsx";
import ProductPage from "./ProductPage.jsx";

createServer((request, response) => {
  const { pipe } = renderToPipeableStream(
    <Document>
      <ProductPage />
    </Document>,
    {
      bootstrapScripts: ["/main.js"],
      onShellReady() {
        response.setHeader("Content-Type", "text/html");
        pipe(response);
      },
    },
  );
}).listen(3000);

Line 2 imports renderToPipeableStream, React's streaming renderer for Node.js. Lines 7 to 10 render the product page inside Document, a component that renders the <html>, <head> and <body> tags, so React writes the whole document. Line 12 asks React to add a script tag for the browser's main.js. Lines 13 to 16 are onShellReady: React calls it as soon as the first part of the page is ready, and line 15 starts sending, by piping React's stream into the response.

In ProductPage, the details take 300 ms and the reviews 600 ms, and each sits in its own Suspense boundary. So the browser receives one response in three moments:

The shell goes first

React can't send a boundary's content before its data arrives, but it can send everything else. That first part is the shell: every element outside every Suspense boundary, plus each boundary's fallback. In this page, the heading and the Add to cart button, from AddToCart, are outside, and the details and the reviews are inside:

Here is the page streaming for real, in the result frame. react-dom/server has a build for browsers, so this example renders the same ProductPage there and adds each chunk to the box at the top, which stands for the visitor's page. Below it, the list shows every chunk of HTML with the time it arrived. Press Run again to watch it again:

1import { renderToReadableStream } from "react-dom/server";2import ProductPage from "./ProductPage.jsx";3import { finish, showChunk } from "./show.js";4 5const started = performance.now();6const stream = await renderToReadableStream(<ProductPage />);7const reader = stream.getReader();8const decoder = new TextDecoder();9 10while (true) {11  const { done, value } = await reader.read();12  if (done) break;13  showChunk(decoder.decode(value), Math.round(performance.now() - started));14}15finish();

Line 6 starts the stream. renderToReadableStream is the Web Streams version of the same renderer; its promise resolves once the shell is ready. Lines 10 to 14 read the stream one chunk at a time, and line 13 hands each chunk and its time to showChunk, in the show.js tab. It adds the chunk to the visitor's page the way a browser adds streamed HTML, running its scripts. The data comes from the data.js tab: 300 ms for the details, 600 ms for the reviews.

The first chunk arrives at once, holding the heading, the button and both fallbacks. Press Edit & run and, in the data.js tab, change the reviews' 600 on line 13 to 2000: the details still come at 300 ms, and the reviews two seconds in. Then open ProductPage.jsx and remove the Suspense boundary around <Reviews /> on lines 14 to 16, keeping <Reviews />: the reviews are now part of the shell, and nothing arrives until they're ready.

How a late chunk takes its place

A chunk that arrives later can't go back and change the HTML the browser already has. So React sends the content at the end of the page, hidden, together with a small script that moves it where it belongs. Step through the recorded stream of the Node.js server above, one chunk at a time:

Press Next chunk once. The first chunk is the whole shell. Each fallback sits between <!--$?--> and <!--/$-->, two HTML comments that mark a boundary still waiting, and a <template id="B:0"> gives the boundary an id. Press it again: the details arrive at 300 ms, inside <div hidden id="S:0">, which the browser doesn't show. The script after it defines React's swap functions, $RC and $RV, then calls $RC("B:0", "S:0"): put the content of S:0 into boundary B:0. The visitor's page now shows the details.

This happens before any of your JavaScript has loaded: the swap is plain DOM code that the server sent. Then try The reviews fail and No boundary around the reviews, and read what each chunk says. Each row of the table is a piece of a streamed boundary, what it means, and who writes it:

Since React 19.2, $RC marks a boundary <!--$~--> and lets $RV reveal it, waiting up to about 300 ms after the previous reveal, so boundaries that arrive close together appear together. In this page they're 300 ms apart, so each shows as it arrives. You can read these scripts in React's source, in the fizz-instruction-set folder (Fizz is the name of React's server renderer).

Node.js streams and Web streams

React has two streaming renderers, because servers speak two kinds of stream. Node.js has its own streams, and renderToPipeableStream writes to one. Deno, edge runtimes like Cloudflare Workers, and browsers use the standard Web Streams, and renderToReadableStream returns one. Since React 19.2 it works in Node.js too, but React still recommends renderToPipeableStream there, because Node.js streams are faster in Node.js. Here is the Node.js server again, with every callback:

import { createServer } from "node:http";
import { renderToPipeableStream } from "react-dom/server";
import Document from "./Document.jsx";
import ProductPage from "./ProductPage.jsx";

createServer((request, response) => {
  let failed = false;
  const { pipe, abort } = renderToPipeableStream(
    <Document>
      <ProductPage />
    </Document>,
    {
      bootstrapScripts: ["/main.js"],
      onShellReady() {
        response.statusCode = failed ? 500 : 200;
        response.setHeader("Content-Type", "text/html");
        pipe(response);
      },
      onShellError(error) {
        response.statusCode = 500;
        response.setHeader("Content-Type", "text/html");
        response.end("<h1>Something went wrong</h1><p>Please try again.</p>");
      },
      onAllReady() {
        console.log("Every Suspense boundary is done");
      },
      onError(error) {
        failed = true;
        console.error(error);
      },
    },
  );
  setTimeout(() => abort(), 10000);
}).listen(3000);

Lines 14 to 18 are onShellReady. Line 15 sets the status code; the status goes out with the first chunk, so it has to be decided before pipe. Lines 19 to 23 are onShellError: the shell itself failed, React has sent nothing, and line 22 sends a small error page instead. Lines 24 to 26 are onAllReady, once every boundary is done. Lines 27 to 30 are onError, for any error, in the shell or a boundary; line 28 remembers it. Line 33 calls abort() after 10 seconds: any boundary still waiting stops waiting, and the browser renders it instead.

Each row is a callback, when React calls it, and what you do there:

The same server for a Web Streams runtime returns a Response:

import { renderToReadableStream } from "react-dom/server";
import Document from "./Document.jsx";
import ProductPage from "./ProductPage.jsx";

export async function handleRequest(request) {
  try {
    const stream = await renderToReadableStream(
      <Document>
        <ProductPage />
      </Document>,
      {
        bootstrapScripts: ["/main.js"],
        signal: AbortSignal.timeout(10000),
        onError(error) {
          console.error(error);
        },
      },
    );
    return new Response(stream, { headers: { "Content-Type": "text/html" } });
  } catch (error) {
    return new Response("<h1>Something went wrong</h1>", {
      status: 500,
      headers: { "Content-Type": "text/html" },
    });
  }
}

Line 7 waits for the shell: the promise resolves when it's ready, and rejects if it fails, which lines 20 to 25 turn into an error page. Line 13 passes an AbortSignal that fires after 10 seconds, the Web Streams way to give up. Line 19 returns the stream as the response body. Each row compares the APIs:

When something fails mid-stream

Where an error happens decides what it costs:

• In the shell. React can't send half a shell, so nothing goes out. It calls onError, then onShellError, where you send your own error page with a 500 status, as lines 19 to 23 of the server do.
• Inside a boundary. Only that boundary is lost. React calls onError, keeps the fallback, and sends $RX("B:1"), which marks the boundary <!--$!-->. When the page hydrates, React renders that boundary in the browser; if it fails there too, the nearest error boundary catches it. Try The reviews fail in the playground.
• Too slow. abort(), or the signal you passed, gives up on every boundary still waiting, the same way: a fallback now, the browser's render later.

A production build sends $RX("B:1") with no message, so visitors can't read your server's errors; a development build adds the message and the component stack. Whatever onError returns is sent as the error's digest, a short code that lets you match the browser's report with your server's log.

One thing streaming changes: the status code goes out with the first chunk. If the shell is sent at 0 ms and the reviews fail at 600 ms, the visitor has already received 200. The reviews' fallback, and the browser's render after it, are what's left to handle it.

Hydrating while the HTML still arrives

The shell ends with the script tag for main.js, so the browser starts downloading it while the rest of the HTML is still on its way. On a real site, main.js hydrates the whole document:

import { hydrateRoot } from "react-dom/client";
import Document from "./Document.jsx";
import ProductPage from "./ProductPage.jsx";

hydrateRoot(
  document,
  <Document>
    <ProductPage />
  </Document>,
);

Lines 5 to 10 hydrate document with the same Document and ProductPage the server rendered. It often runs before the stream has ended. That's what selective hydration is for: React hydrates the shell, and leaves each boundary that's still waiting. When its chunk arrives, $RV calls the retry function React left on the boundary, and React hydrates it then. This example does all of it in the result frame: it streams the page, and hydrates the visitor's page right after the first chunk. Click Add to cart straight away, then Helpful once the reviews are in:

1import { hydrateRoot } from "react-dom/client";2import { renderToReadableStream } from "react-dom/server";3import ProductPage from "./ProductPage.jsx";4import { finish, showChunk } from "./show.js";5 6const started = performance.now();7const stream = await renderToReadableStream(<ProductPage />);8const reader = stream.getReader();9const decoder = new TextDecoder();10let hydrated = false;11 12while (true) {13  const { done, value } = await reader.read();14  if (done) break;15  showChunk(decoder.decode(value), Math.round(performance.now() - started));16  if (!hydrated) {17    // main.js arrives while the rest of the HTML is still streaming.18    hydrateRoot(document.getElementById("visitor"), <ProductPage />);19    hydrated = true;20  }21}22finish();

Lines 16 to 20 call hydrateRoot once, after the first chunk, as main.js would. The button counts your clicks while the reviews are still on their way, and Helpful works as soon as the reviews appear: React hydrated each boundary when its chunk arrived.

The count lives in its own component, AddToCart (its own tab), on purpose: a click re-renders only the button. If the count lived in ProductPage, a click would re-render the boundaries' parent while they still wait for their HTML. React can't hydrate them at that moment, so it would drop the server's HTML for them and render them in the browser, fallbacks first. While the HTML streams, the page is still loading; if it had finished loading with a boundary still waiting, React would stop waiting and render that boundary itself. That's why show.js, lines 3 and 16 to 19, tells React the page is loading until the stream ends. You can read that check in registerSuspenseInstanceRetry, in React 19.3.1. Hydration inside shows how React leaves a waiting boundary and comes back to it.

Prerendering: wait for everything, ahead of time

Some pages are the same for every visitor, like a tea's description page. You can render them once, when you build the site, and save the HTML. Streaming doesn't help there: nobody is waiting. React 19 added prerender and prerenderToNodeStream, in react-dom/static, which wait for every Suspense boundary:

import { prerenderToNodeStream } from "react-dom/static";
import { createWriteStream } from "node:fs";
import Document from "./Document.jsx";
import ProductPage from "./ProductPage.jsx";

const { prelude } = await prerenderToNodeStream(
  <Document>
    <ProductPage />
  </Document>,
  { bootstrapScripts: ["/main.js"] },
);
prelude.pipe(createWriteStream("dist/green-tea.html"));

Line 6 resolves only when the details and the reviews are both in, so prelude holds the finished page: every boundary is <!--$-->, with no fallbacks and no swap scripts. Line 12 writes it to a file a web server can send as it is. A crawler gets the same complete HTML from a streaming server if you pipe in onAllReady instead of onShellReady, or, with Web Streams, after await stream.allReady.

React 19.2 went one step further: prerender can stop at the parts that change per request, and return a postponed state with its HTML. Later, for each request, resume (or resumeToPipeableStream) streams just the rest. This is called partial prerendering: the parts that are the same for everyone can be served at once from a cache, and the rest filled in for each request.

How frameworks stream your pages

You rarely call these APIs yourself; a framework does, and you choose where the Suspense boundaries go. Two common ones (checked in October 2026):

• React Router, in its default server entry for Node.js (entry.server.node.tsx), calls renderToPipeableStream. It pipes in onShellReady for people and in onAllReady for crawlers it recognizes, and calls abort() after a timeout, like the server in this lesson.
• Next.js has streaming built into its App Router. A loading.js file next to a page wraps the page in a Suspense boundary with that file as the fallback, and your own <Suspense> boundaries stream inside it.

In both, the shell is whatever you leave outside your boundaries. Put a boundary around each part that waits on slow data, keep the parts people need first outside, and let the rest stream. The React frameworks lesson covers frameworks. Sort these parts of the lesson's page by the chunk they arrive in:

Common mix-ups

• "Streaming sends one request per boundary." No. It's one response that stays open; each chunk is more HTML in the same response.
• "The browser needs React to show streamed content." No. The swap is a small script inside the HTML. The details appear before main.js has loaded; React only needs to arrive to make them work.
• "Streaming makes slow data faster." No. The reviews still take 600 ms. What changes is that nothing else waits for them.
• "An error after the shell can still turn into a 500 page." No. The status went out with the first chunk. A failed boundary keeps its fallback, and the browser renders it.
• "Every component streams on its own." No. Only Suspense boundaries can arrive later. Anything outside them is part of the shell and holds it up.
• "Crawlers see the fallbacks." Only if you send them the stream as it goes. Pipe in onAllReady for crawlers, or prerender the page.

Practice exercises

The live exercises stream a page in the result frame and print each chunk with its time in the console. The server exercises are Node.js code, so they have no result; check your answer against the lesson's callbacks.

import { Suspense, use } from "react";
import { renderToReadableStream } from "react-dom/server";

const later = (ms, value) => new Promise((resolve) => setTimeout(() => resolve(value), ms));
const stock = later(500, "12 in stock");
const reviews = later(900, "4 stars from Ravi");

function Stock() {
  return <p>{use(stock)}</p>;
}

function Reviews() {
  return <p>{use(reviews)}</p>;
}

function TeaPage() {
  return (
    <main>
      <h1>Jasmine tea</h1>
      <Suspense fallback={<p>Checking stock...</p>}>
        <Stock />
      </Suspense>
      <Suspense fallback={<p>Loading reviews...</p>}>
        <Reviews />
      </Suspense>
    </main>
  );
}

const started = performance.now();
const stream = await renderToReadableStream(<TeaPage />);
const reader = stream.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const ms = Math.round(performance.now() - started);
  console.log(`+${ms} ms:`, decoder.decode(value));
}

1import { Suspense, use } from "react";2import { renderToReadableStream } from "react-dom/server";3 4const later = (ms, value) => new Promise((resolve) => setTimeout(() => resolve(value), ms));5const stock = later(500, "12 in stock");6const reviews = later(900, "4 stars from Ravi");7 8function Stock() {9  return <p>{use(stock)}</p>;10}11 12function Reviews() {13  return <p>{use(reviews)}</p>;14}15 16function TeaPage() {17  return (18    <main>19      <h1>Jasmine tea</h1>20      <Suspense fallback={<p>Checking stock...</p>}>21        <Stock />22      </Suspense>23      <Suspense fallback={<p>Loading reviews...</p>}>24        <Reviews />25      </Suspense>26    </main>27  );28}29 30const started = performance.now();31const stream = await renderToReadableStream(<TeaPage />);32const reader = stream.getReader();33const decoder = new TextDecoder();34while (true) {35  const { done, value } = await reader.read();36  if (done) break;37  const ms = Math.round(performance.now() - started);38  console.log(`+${ms} ms:`, decoder.decode(value));39}

import { Suspense, use } from "react";
import { renderToReadableStream } from "react-dom/server";

const stock = new Promise((resolve) => setTimeout(() => resolve("12 in stock"), 500));

function Stock() {
  return <p>{use(stock)}</p>;
}

function TeaPage() {
  return (
    <main>
      <h1>Jasmine tea</h1>
      <Suspense fallback={<p>Checking stock...</p>}>
        <Stock />
      </Suspense>
    </main>
  );
}

const started = performance.now();
const stream = await renderToReadableStream(<TeaPage />);
const reader = stream.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const ms = Math.round(performance.now() - started);
  console.log(`+${ms} ms:`, decoder.decode(value));
}

1import { Suspense, use } from "react";2import { renderToReadableStream } from "react-dom/server";3 4const stock = new Promise((resolve) => setTimeout(() => resolve("12 in stock"), 500));5 6function Stock() {7  return <p>{use(stock)}</p>;8}9 10function TeaPage() {11  return (12    <main>13      <h1>Jasmine tea</h1>14      <Suspense fallback={<p>Checking stock...</p>}>15        <Stock />16      </Suspense>17    </main>18  );19}20 21const started = performance.now();22const stream = await renderToReadableStream(<TeaPage />);23const reader = stream.getReader();24const decoder = new TextDecoder();25while (true) {26  const { done, value } = await reader.read();27  if (done) break;28  const ms = Math.round(performance.now() - started);29  console.log(`+${ms} ms:`, decoder.decode(value));30}

1import { Suspense, use } from "react";2import { renderToReadableStream } from "react-dom/server";3 4const reviews = new Promise((resolve) => setTimeout(() => resolve("5 stars from Asha"), 600));5 6function Reviews() {7  return <p>{use(reviews)}</p>;8}9 10function ProductPage() {11  return (12    <main>13      <h1>Green tea</h1>14      <Reviews />15    </main>16  );17}18 19const started = performance.now();20const stream = await renderToReadableStream(<ProductPage />);21const reader = stream.getReader();22const decoder = new TextDecoder();23while (true) {24  const { done, value } = await reader.read();25  if (done) break;26  const ms = Math.round(performance.now() - started);27  console.log(`+${ms} ms:`, decoder.decode(value));28}

1import { Suspense, use } from "react";2import { renderToReadableStream } from "react-dom/server";3 4const reviews = new Promise((resolve) => setTimeout(() => resolve("5 stars from Asha"), 600));5 6function Reviews() {7  return <p>{use(reviews)}</p>;8}9 10function ProductPage() {11  return (12    <main>13      <h1>Green tea</h1>14      <Suspense fallback={<p>Loading reviews...</p>}>15        <Reviews />16      </Suspense>17    </main>18  );19}20 21const started = performance.now();22const stream = await renderToReadableStream(<ProductPage />);23const reader = stream.getReader();24const decoder = new TextDecoder();25while (true) {26  const { done, value } = await reader.read();27  if (done) break;28  const ms = Math.round(performance.now() - started);29  console.log(`+${ms} ms:`, decoder.decode(value));30}

createServer((request, response) => {
  const { pipe } = renderToPipeableStream(<Page />, {
    onShellReady() {
      response.setHeader("Content-Type", "text/html");
      pipe(response);
    },
    onError(error) {
      console.error(error);
    },
  });
}).listen(3000);

createServer((request, response) => {
  let failed = false;
  const { pipe } = renderToPipeableStream(<Page />, {
    onShellReady() {
      response.statusCode = failed ? 500 : 200;
      response.setHeader("Content-Type", "text/html");
      pipe(response);
    },
    onError(error) {
      failed = true;
      console.error(error);
    },
  });
}).listen(3000);

createServer((request, response) => {
  const { pipe } = renderToPipeableStream(<Page />, {
    onShellReady() {
      response.setHeader("Content-Type", "text/html");
      pipe(response);
    },
  });
}).listen(3000);

const crawlers = /bot|crawler|spider/i;

createServer((request, response) => {
  const isCrawler = crawlers.test(request.headers["user-agent"] ?? "");
  const ready = isCrawler ? "onAllReady" : "onShellReady";
  const { pipe } = renderToPipeableStream(<Page />, {
    [ready]() {
      response.setHeader("Content-Type", "text/html");
      pipe(response);
    },
  });
}).listen(3000);

1import { Suspense, use } from "react";2import { renderToReadableStream } from "react-dom/server";3 4const reviews = new Promise((resolve) => setTimeout(() => resolve("5 stars from Asha"), 600));5 6function Reviews() {7  return <p>{use(reviews)}</p>;8}9 10function ProductPage() {11  return (12    <main>13      <h1>Green tea</h1>14      <Suspense fallback={<p>Loading reviews...</p>}>15        <Reviews />16      </Suspense>17    </main>18  );19}20 21const started = performance.now();22const stream = await renderToReadableStream(<ProductPage />);23const reader = stream.getReader();24const decoder = new TextDecoder();25while (true) {26  const { done, value } = await reader.read();27  if (done) break;28  const ms = Math.round(performance.now() - started);29  console.log(`+${ms} ms:`, decoder.decode(value));30}

1import { Suspense, use } from "react";2import { renderToReadableStream } from "react-dom/server";3 4const reviews = new Promise((resolve) => setTimeout(() => resolve("5 stars from Asha"), 600));5 6function Reviews() {7  return <p>{use(reviews)}</p>;8}9 10function ProductPage() {11  return (12    <main>13      <h1>Green tea</h1>14      <Suspense fallback={<p>Loading reviews...</p>}>15        <Reviews />16      </Suspense>17    </main>18  );19}20 21const started = performance.now();22const stream = await renderToReadableStream(<ProductPage />, {23  signal: AbortSignal.timeout(400),24});25const reader = stream.getReader();26const decoder = new TextDecoder();27while (true) {28  const { done, value } = await reader.read();29  if (done) break;30  const ms = Math.round(performance.now() - started);31  console.log(`+${ms} ms:`, decoder.decode(value));32}

Check your understanding

For each question, ask what's in the shell, and which chunk each part arrives in.

Key takeaways

• Streaming sends a page's HTML in pieces over one response: the shell at once, then each Suspense boundary when its data is ready. Nothing waits for the slowest part.
• The shell is everything outside every boundary, plus the fallbacks. Anything that waits outside a boundary holds up the whole page.
• A later chunk sends the content hidden, then $RC moves it into the boundary in place of its fallback, before React's JavaScript has loaded.
• Use renderToPipeableStream in Node.js and renderToReadableStream with Web Streams. Pipe in onShellReady for people, onAllReady for crawlers, handle onShellError, and give up on slow parts with abort or a signal.
• A boundary that fails or times out keeps its fallback and is rendered by the browser. Boundaries hydrate one at a time as they arrive; prerender waits for everything, for pages built ahead of time.

Coming next: Metadata, stylesheets and resource hints. React 19 lets your components render the page's title, meta tags and stylesheets, and tells the browser what to download early.