Skip to content
Tutorials Center
My learning

Topics

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.

JSX
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.

A build step that writes files

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):

JSX
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);
}
Time limit and the fallback

Syntax

JSX
const { prelude, postponed } = await prerenderToNodeStream(reactNode, options?);
TypeScript
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 AbortController after a limit.
  • Read the stream once. prelude is a one-shot Readable; use pipeline or for await on it.
  • A nonce option 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. null means the page is complete. Anything else means holes remain, and resumeToPipeableStream can 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.