Skip to content
Tutorials Center
My learning

Topics

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

React renderToPipeableStream function

Reference for react-dom/server renderToPipeableStream: stream HTML to a Node.js response, with onShellReady, onAllReady, onError, abort and the options.

renderToPipeableStream renders a React tree to a Node.js stream. It starts writing HTML as soon as the "shell" is ready: everything outside Suspense boundaries that are still waiting. The slow parts are sent later in the same response, and a few inline scripts swap each fallback for the real content when it arrives.

It exists only in the Node.js build of react-dom/server (on Deno, Bun and Cloudflare use renderToReadableStream). The function returns two controls, pipe and abort, and everything else happens in callbacks.

JSX
import { renderToPipeableStream } from 'react-dom/server';

const { pipe, abort } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    response.setHeader('Content-Type', 'text/html');
    pipe(response);
  },
});

Try it

The browser build of react-dom/server has no renderToPipeableStream, so a live page cannot call it. renderToReadableStream runs the same renderer and writes the same bytes, so these two examples show what a pipeable stream writes. The Node.js version is the read-only snippet in the next section.

What the stream writes

The first part is the shell with the fallback (wait) inside a placeholder; the second part is a hidden <div id="S:0"> with the finished content, which an inline script moves into place. The long scripts are shortened here.

Shell errors versus boundary errors

A failure in the shell rejects (with renderToPipeableStream it calls onShellError instead, and you send a 500 page). A failure inside a boundary only logs, and the page still streams, with the fallback and a marker that makes the client retry. Dev-mode React also prints the errors to the console.

Syntax

JSX
const { pipe, abort } = renderToPipeableStream(reactNode, options?);
TypeScript
function renderToPipeableStream(
  children: ReactNode,
  options?: {
    identifierPrefix?: string;
    namespaceURI?: string;
    nonce?: string;
    bootstrapScriptContent?: string;
    bootstrapScripts?: (string | { src: string; integrity?: string; crossOrigin?: string })[];
    bootstrapModules?: (string | { src: string; integrity?: string; crossOrigin?: string })[];
    importMap?: { imports?: Record<string, string>; scopes?: Record<string, Record<string, string>> };
    progressiveChunkSize?: number;
    onShellReady?: () => void;
    onShellError?: (error: unknown) => void;
    onAllReady?: () => void;
    onError?: (error: unknown, info: { componentStack?: string }) => string | void;
    onHeaders?: (headers: Record<string, string>) => void;
  }
): { pipe<W extends NodeJS.WritableStream>(destination: W): W; abort(reason?: unknown): void };
Name Description
onShellReady The shell has rendered. Call pipe(response) here for normal browser requests.
onShellError The shell failed, so nothing was written yet. Send an error page and a 500 status.
onAllReady Every boundary has finished. Pipe here instead of in onShellReady for crawlers or static generation.
onError Called for every error, inside or outside the shell. Log it; the string you return becomes the error digest.
bootstrapScripts, bootstrapModules, bootstrapScriptContent, nonce, importMap Script tags for hydration. See Bootstrap scripts and options.
progressiveChunkSize Rough byte size at which React stops inlining a boundary and streams it separately.
onHeaders Receives early hints (such as Link preload headers) as an object, when the shell is ready.

Returns: { pipe, abort }. Call pipe once with a writable stream. abort(reason) stops waiting: unfinished boundaries stay as fallbacks and the client finishes them.

Usage notes

  • A typical Node handler:
JSX
import { renderToPipeableStream } from 'react-dom/server';

app.get('/', (request, response) => {
  let didError = false;
  const { pipe, abort } = renderToPipeableStream(<App />, {
    bootstrapScripts: ['/main.js'],
    onShellReady() {
      response.statusCode = didError ? 500 : 200;
      response.setHeader('Content-Type', 'text/html');
      pipe(response);
    },
    onShellError() {
      response.statusCode = 500;
      response.send('<h1>Something went wrong</h1>');
    },
    onError(error) {
      didError = true;
      console.error(error);
    },
  });
  setTimeout(abort, 10_000);
});
  • Set a timeout with abort(), otherwise a promise that never settles keeps the response open forever.
  • Status codes are decided before the first byte. Once the shell is written the status line is gone, so errors in boundaries cannot change it.
  • Order of callbacks (checked on a tree with one slow boundary): onShellReady, then onAllReady, then the stream finishes. For a shell error, onError fires first and onShellError after it.
  • Crawlers and tests want the full document: wait for onAllReady before calling pipe.
  • Hydration pairs it with hydrateRoot; boundaries hydrate independently as their content arrives.
  • Compression middleware must flush after each chunk, or the progressive output is buffered.
  • Only the Node build has this function. Other runtimes use the web-stream version.