Skip to content
Tutorials Center
My learning

Topics

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

React prerender function

Reference for react-dom/static prerender: render a React tree to static HTML after all Suspense data has loaded, with abort signals, postponed state and options.

prerender renders a React tree to static HTML and waits until all the data is ready. It is the function for static site generation: you call it at build time (or on a schedule), and it returns the complete page as a stream of bytes. Unlike renderToString, it supports Suspense and use; unlike renderToReadableStream, it does not deliver the shell early and the rest later, it hands over one finished document.

It comes from react-dom/static, not react-dom/server, and it uses web streams. The Node.js variant is prerenderToNodeStream. Both return a prelude and a postponed value. If everything finished, postponed is null; if you aborted early, the prelude holds the shell with fallbacks and postponed lets you resume later.

JSX
import { prerender } from 'react-dom/static';

const { prelude, postponed } = await prerender(<App />, {
  bootstrapScripts: ['/main.js'],
});

Try it

The browser build of the packages does not include react-dom/static, so the live examples use renderToReadableStream and wait for allReady. For a tree that finishes, it produces the same body that prerender puts in its prelude. The real prerender calls are in the read-only snippets.

Generate pages like a build step

Each file holds finished content inside <!--$--> markers, with no fallback and no later patch scripts, because the data was ready before the first byte was written.

Stopping early leaves the fallback

With the real prerender, aborting the same way also returns a postponed object, so the missing part can be added later.

Syntax

JSX
const { prelude, postponed } = await prerender(reactNode, options?);
TypeScript
function prerender(
  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: Headers) => void;
  }
): Promise<{ prelude: ReadableStream<Uint8Array>; postponed: object | null }>;
Name Description
reactNode The tree to render, normally the whole <html> document.
signal Aborts the render. Unfinished boundaries stay as fallbacks and postponed is filled in.
onError Called for each error; the string it returns becomes the error digest.
Script options bootstrapScripts, bootstrapModules, bootstrapScriptContent, importMap and identifierPrefix; see Bootstrap scripts and options.

Returns: a promise of { prelude, postponed }. prelude is a ReadableStream of bytes; postponed is null for a completed render.

Errors: the promise rejects when the shell fails. Errors inside a boundary go to onError and leave the fallback in the output.

Usage notes

  • It waits for everything. If one promise never settles, so does prerender. Always pass a signal with a timeout in build scripts.
  • No nonce option. A static file cannot carry a per-request nonce.
  • Rendering a full <html> tree adds <!DOCTYPE html> at the start of the prelude.
  • Result is a stream. Read it to a string with new Response(prelude).text(), or write it to a file stream.
  • Good for caching: the prelude can be stored and served from a CDN. Pair it with hydration through hydrateRoot.
  • Use renderToReadableStream for live requests. It sends the shell before slow data arrives, which prerender never does.
  • Partial prerendering: abort on purpose, keep the postponed value, and finish later with resume.
  • Data fetching should happen in the tree, with use or a framework loader. Components that rely on browser APIs still need effects, since no effects run here.