React Reference ยท react-dom/server and Static APIs
React prerenderToNodeStream function
Reference for react-dom/static prerenderToNodeStream: prerender a React tree to a Node.js Readable after all data loads, and write it to a file or response.
prerenderToNodeStream is the Node.js flavor of prerender. It waits until every Suspense boundary has its data, then hands you the finished HTML as a Node Readable stream in the prelude property. You pipe it to a file during a build, to an HTTP response, or into stream/consumers.
Everything else matches prerender: the options, the postponed value for aborted renders, and the behavior of errors. The differences are the type of the stream and the type of the onHeaders argument (a plain object instead of a Headers instance). It is exported from react-dom/static and works in Node.js, not in browsers or edge runtimes.
import { prerenderToNodeStream } from 'react-dom/static'; const { prelude, postponed } = await prerenderToNodeStream(<App />, { bootstrapScripts: ['/main.js'], });
Try it
Because the browser cannot import react-dom/static, this example runs the closest browser equivalent, renderToReadableStream after allReady, and collects the result into one string per page. The Node.js build script is the read-only snippet after it.
Both files contain the finished greeting with its <!--$--> markers. The <!-- --> between "Hello," and the name is the separator between adjacent text nodes.
This is what the same build looks like in Node.js (read-only):
import { createWriteStream } from 'node:fs'; import { pipeline } from 'node:stream/promises'; import { prerenderToNodeStream } from 'react-dom/static'; const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), 10_000); try { const { prelude, postponed } = await prerenderToNodeStream(<App />, { bootstrapScripts: ['/assets/main.js'], signal: controller.signal, onError(error) { console.error('render error', error); }, }); await pipeline(prelude, createWriteStream('dist/index.html')); if (postponed !== null) { console.warn('Some parts were left for request time.'); } } finally { clearTimeout(timer); }
Syntax
const { prelude, postponed } = await prerenderToNodeStream(reactNode, options?);
function prerenderToNodeStream( children: ReactNode, options?: { identifierPrefix?: string; namespaceURI?: 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; signal?: AbortSignal; onError?: (error: unknown, info: { componentStack?: string }) => string | void; onHeaders?: (headers: Record<string, string>) => void; } ): Promise<{ prelude: import('node:stream').Readable; postponed: object | null }>;
| Name | Description |
|---|---|
reactNode |
The tree to render, usually a full document. |
signal |
An AbortSignal that ends the wait. Unfinished boundaries keep their fallbacks and postponed is set. |
onError |
Called for every error, in the shell or in a boundary. |
onHeaders |
Called with preload hints as a plain object, so a server can send them as an early Link header. |
| Script options | See Bootstrap scripts and options. |
Returns: a promise of { prelude, postponed }, where prelude is a Node Readable.
Errors: the promise rejects if the shell throws. Boundary errors are reported to onError.
Usage notes
- Always use a timeout. A promise that never settles keeps the build hanging; abort with
AbortControllerafter a limit. - Read the stream once.
preludeis a one-shotReadable; usepipelineorfor awaiton it. - A
nonceoption has no effect here, since the file is generated ahead of the request. - The doctype is automatic when the root element is
<html>. - Check
postponed.nullmeans the page is complete. Anything else means holes remain, andresumeToPipeableStreamcan fill them at request time. - Run it in your build, not in the page. Only the HTML is shipped; client JavaScript hydrates it with
hydrateRoot.