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.
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.
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.
With the real prerender, aborting the same way also returns a postponed object, so the missing part can be added later.
Syntax
const { prelude, postponed } = await prerender(reactNode, options?);
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 asignalwith a timeout in build scripts. - No
nonceoption. 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
renderToReadableStreamfor live requests. It sends the shell before slow data arrives, which prerender never does. - Partial prerendering: abort on purpose, keep the
postponedvalue, and finish later withresume. - Data fetching should happen in the tree, with
useor a framework loader. Components that rely on browser APIs still need effects, since no effects run here.