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.
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.
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.
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
const { pipe, abort } = renderToPipeableStream(reactNode, options?);
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:
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, thenonAllReady, then the stream finishes. For a shell error,onErrorfires first andonShellErrorafter it. - Crawlers and tests want the full document: wait for
onAllReadybefore callingpipe. - 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.