react dom: static

49 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

prerender function

prerender renders a React tree to static HTML with a Readable Web Stream. It is available in environments with Web Streams, which includes browsers, Deno, and some modern edge runtimes.

react-dom/static APIs overview

The react-dom/static APIs generate static HTML for React components. They have limited functionality compared to streaming APIs. Most components do not need to import or use them directly; frameworks may call them.

Web Streams APIs performance in Node.js

While prerender and resumeAndPrerender are available in Node.js for compatibility, they are not recommended due to worse performance. The dedicated Node.js APIs (prerenderToNodeStream and resumeAndPrerenderToNodeStream) should be used instead.

resumeAndPrerenderToNodeStream function

resumeAndPrerenderToNodeStream continues a prerendered React tree to static HTML with a Node.js Stream. It is available in environments with Node.js Streams and is recommended for use in Node.js environments instead of the Web Streams APIs.

prerenderToNodeStream function

prerenderToNodeStream renders a React tree to static HTML with a Node.js Stream. It is available in environments with Node.js Streams and is recommended for use in Node.js environments instead of the Web Streams APIs.

resumeAndPrerender function

resumeAndPrerender continues a prerendered React tree to static HTML with a Readable Web Stream. It is available in environments with Web Streams, which includes browsers, Deno, and some modern edge runtimes.

resumeAndPrerender parameters

resumeAndPrerender accepts three parameters: reactNode (the React node to prerender, typically a JSX element like <App /> representing the entire document), postponedState (the opaque postpone object returned from a prerender API, loaded from storage), and an optional options object containing signal (an abort signal), onBrowserBailout (a callback for when browser-only rendering occurs), and onError (a callback for server errors).

resumeAndPrerender use cases

resumeAndPrerender is used for static server-side generation (SSG). Unlike renderToString, it waits for all data to load before resolving, making it suitable for generating static HTML for a full page including data fetched with Suspense. It can be aborted and later continued with another resumeAndPrerender or resumed with resume to support partial pre-rendering. To stream content as it loads, use renderToReadableStream instead.

resumeAndPrerender and nonce caveat

nonce is not an available option when prerendering because nonces must be unique per request, and including a nonce value in the prerender itself would be inappropriate and insecure for applications using CSP (Content Security Policy).

resumeAndPrerender Web Streams requirement

resumeAndPrerender depends on Web Streams API. For Node.js environments, use resumeAndPrerenderToNodeStream instead.

resumeAndPrerender example usage

Example: import { resumeAndPrerender } from 'react-dom/static'; import { getPostponedState } from 'storage'; async function handler(request, response) { const postponedState = getPostponedState(request); const { prelude } = await resumeAndPrerender(<App />, postponedState, { bootstrapScripts: ['/main.js'] }); return new Response(prelude, { headers: { 'content-type': 'text/html' }, }); }. On the client, call hydrateRoot to make the server-generated HTML interactive.

resumeAndPrerender signature

resumeAndPrerender is imported from 'react-dom/static' and has the signature: const {prelude, postponed} = await resumeAndPrerender(reactNode, postponedState, options?). It continues a prerendered React tree to a static HTML string using a Web Stream.

resumeAndPrerender return value

resumeAndPrerender returns a Promise that resolves to an object containing prelude (a Web Stream of HTML that can be sent in chunks or read into a string) and postponed (a JSON-serializable opaque object that can be passed to resume or resumeAndPrerender if prerender is aborted). If rendering fails, the Promise is rejected.

prerenderToNodeStream signature

The signature of prerenderToNodeStream is: const {prelude, postponed} = await prerenderToNodeStream(reactNode, options?). It renders a React tree to a static HTML string using a Node.js Stream.

prerenderToNodeStream parameters

Parameters for prerenderToNodeStream: reactNode (required) - A React node representing the entire document, typically with the root <html> tag. options (optional) object with: bootstrapScriptContent (optional, string) - placed in inline <script> tag; bootstrapScripts (optional, array of strings) - URLs for <script> tags, include the script calling hydrateRoot or omit if no client-side React; bootstrapModules (optional, array) - like bootstrapScripts but emits <script type="module"> instead; identifierPrefix (optional, string) - prefix for IDs generated by useId, must match hydrateRoot prefix; importMap (optional, object) - import map with imports and scopes properties, emitted as inline <script type="importmap">; maxHeadersLength (optional, number, default 2000) - maximum UTF-16 code units for header content passed to onHeaders; namespaceURI (optional, string, default regular HTML) - root namespace URI, use 'http://www.w3.org/2000/svg' for SVG or 'http://www.w3.org/1998/Math/MathML' for MathML; onBrowserBailout (optional, callback) - called when React recovers from browser() by leaving Suspense fallback, receives Error and errorInfo with componentStack; onError (optional, callback) - fires on server errors whether recoverable or not, defaults to console.error; onHeaders (optional, callback) - fires when React determines resource hints, receives Headers instance with Link header value; progressiveChunkSize (optional, number) - number of bytes in a chunk; signal (optional, AbortSignal) - lets you abort prerendering and render rest on client.

prerenderToNodeStream return value

prerenderToNodeStream returns a Promise that either resolves to an object containing prelude (a Node.js Stream of HTML) and postponed (a JSON-serializable opaque object for resuming with resumeToPipeableStream if rendering did not finish, otherwise null), or rejects if rendering fails.

prerenderToNodeStream aborting with timeout

async function renderToString() { const controller = new AbortController(); setTimeout(() => { controller.abort() }, 10000); try { const {prelude} = await prerenderToNodeStream(<App />, { signal: controller.signal, }); } }

prerenderToNodeStream waits for all Suspense to resolve

prerenderToNodeStream waits for all data to load before finishing static HTML generation and resolving. It will wait for all Suspense boundaries to resolve. Only data read from sources that activate a Suspense boundary, such as a Promise read with use(), will suspend during rendering. Data fetched inside an Effect or event handler will not suspend.

prerenderToNodeStream abort behavior

When prerenderToNodeStream is aborted, the prelude will contain all HTML that was prerendered before the abort. Any Suspense boundaries with incomplete children will be included in the prelude in the fallback state. This can be used for partial prerendering with resumeToPipeableStream or resumeAndPrerenderToNodeStream.

prerenderToNodeStream stream to string example

import { prerenderToNodeStream } from 'react-dom/static'; async function renderToString() { const {prelude} = await prerenderToNodeStream(<App />, { bootstrapScripts: ['/main.js'] }); return new Promise((resolve, reject) => { let data = ''; prelude.on('data', chunk => { data += chunk; }); prelude.on('end', () => resolve(data)); prelude.on('error', reject); }); }

prerenderToNodeStream basic example

import { prerenderToNodeStream } from 'react-dom/static'; app.use('/', async (request, response) => { const { prelude } = await prerenderToNodeStream(<App />, { bootstrapScripts: ['/main.js'], }); response.setHeader('Content-Type', 'text/plain'); prelude.pipe(response); });

prerenderToNodeStream Node.js specific

prerenderToNodeStream is specific to Node.js. Environments with Web Streams like Deno and modern edge runtimes should use prerender instead.

prerenderToNodeStream does not stream incrementally

prerenderToNodeStream does not support streaming more content as it loads. The response waits for the entire app to finish rendering, including all Suspense boundaries, before resolving. For streaming content as it loads, use renderToPipeableStream instead.

prerender injects doctype and bootstrap scripts

React automatically injects the doctype and bootstrap <script> tags into the resulting HTML stream. For example, if bootstrapScripts: ['/main.js'] is provided, the output will include <script src="/main.js" async=""></script>.

prerender signature and basic usage

prerender is called with a React node and optional options object. It returns a Promise that resolves to an object containing prelude (a Web Stream of HTML) and postponed (a JSON-serializeable opaque object for resuming, or null if rendering completed). The signature is: const {prelude, postponed} = await prerender(reactNode, options?)

prerender Web Streams dependency

prerender API depends on Web Streams. For Node.js environments, use prerenderToNodeStream instead.

prerender parameters

prerender takes two parameters: (1) reactNode - a React node representing the entire document, expected to render the <html> tag; (2) options - optional object with: bootstrapScriptContent (string placed in inline <script> tag), bootstrapScripts (array of script URLs), bootstrapModules (like bootstrapScripts but uses <script type="module">), identifierPrefix (string prefix for useId-generated IDs, must match hydrateRoot prefix), importMap (import map object with imports and scopes), maxHeadersLength (max header content length in UTF-16 code units, defaults to 2000), namespaceURI (root namespace URI string, defaults to HTML, use 'http://www.w3.org/2000/svg' for SVG or 'http://www.w3.org/1998/Math/MathML' for MathML), onBrowserBailout (callback when recovering from browser() by leaving Suspense fallback), onError (callback for server errors), onHeaders (callback when resource hints determined, receives Headers instance with Link header), progressiveChunkSize (bytes per chunk), signal (AbortSignal to abort prerendering).

prerender caveat: nonce not available

The nonce option is not available when prerendering. Nonces must be unique per request and including the nonce value in the prerender itself would be inappropriate and insecure for CSP.

prerender use case: static site generation

prerender is used for static server-side generation (SSG). Unlike renderToString, prerender waits for all data to load before resolving. This makes it suitable for generating static HTML for a full page, including data fetched using Suspense. To stream content as it loads, use streaming server-side render APIs like renderToReadableStream.

prerender can be aborted and resumed

prerender can be aborted using the signal option and later either continued with resumeAndPrerender or resumed with resume to support partial pre-rendering. Any Suspense boundaries with incomplete children will be included in the prelude in the fallback state.

prerender returns Promise with prelude Web Stream

If rendering is successful, prerender resolves to an object containing: prelude (a Web Stream of HTML that can be sent in chunks or read into a string) and postponed (a JSON-serializeable opaque object for resume if prerender did not finish, or null if prelude contains all content). If rendering fails, the Promise is rejected.

prerender waits for Suspense boundaries to resolve

prerender waits for all data to load before finishing, including waiting for all Suspense boundaries to resolve. Only data read from a source that activates a Suspense boundary, such as a Promise read with use, will suspend during rendering. Suspense does not detect data fetched inside an Effect or event handler.

prerender example: rendering to Response

Example of using prerender to render an app and return as HTTP Response: ```js import { prerender } from 'react-dom/static'; async function handler(request) { const {prelude} = await prerender(<App />, { bootstrapScripts: ['/main.js'] }); return new Response(prelude, { headers: { 'content-type': 'text/html' }, }); } ```

prerender example: rendering to string

Example of converting prerender Web Stream to string: ```js import { prerender } from 'react-dom/static'; async function renderToString() { const {prelude} = await prerender(<App />, { bootstrapScripts: ['/main.js'] }); const reader = prelude.getReader(); let content = ''; while (true) { const {done, value} = await reader.read(); if (done) { return content; } content += Buffer.from(value).toString('utf8'); } } ```

prerender example: aborting with timeout

Example of aborting prerender after a timeout: ```js async function renderToString() { const controller = new AbortController(); setTimeout(() => { controller.abort() }, 10000); try { const {prelude} = await prerender(<App />, { signal: controller.signal, }); // ... } } ```

prerender limitation: no streaming before complete

prerender waits for the entire app to finish rendering, including all Suspense boundaries resolving, before the response resolves. It does not support streaming content as it loads. To stream content as it loads, use renderToReadableStream instead.

prerender root component must render html tag

The root component passed to prerender must return the entire document including the root <html> tag, along with proper <head> and <body> tags.

prerender requires hydrateRoot on client

On the client side, after prerendering with prerender on the server, call hydrateRoot to hydrate the server-generated HTML and make it interactive. The client bootstrap script should call hydrateRoot(document, <App />).

resumeAndPrerenderToNodeStream example usage

Example: import { resumeAndPrerenderToNodeStream } from 'react-dom/static'; import { getPostponedState } from 'storage'; async function handler(request, writable) { const postponedState = getPostponedState(request); const { prelude } = await resumeAndPrerenderToNodeStream(<App />, JSON.parse(postponedState)); prelude.pipe(writable); }. On the client, call hydrateRoot to make the server-generated HTML interactive.

resumeAndPrerenderToNodeStream nonce caveat

nonce is not an available option when prerendering because nonces must be unique per request. Using nonces to secure an application with CSP means the nonce value should not be included in the prerender itself.

resumeAndPrerenderToNodeStream use case

resumeAndPrerenderToNodeStream is used for static server-side generation (SSG). Unlike renderToString, it waits for all data to load before resolving, making it suitable for generating static HTML for a full page including data fetched with Suspense. It can be aborted and later continued with another resumeAndPrerenderToNodeStream or resumed with resume to support partial pre-rendering.

resumeAndPrerenderToNodeStream signature

The signature is: const {prelude, postponed} = await resumeAndPrerenderToNodeStream(reactNode, postponedState, options?). It is an async function that takes a React node, a postponedState object, and optional options, returning a Promise that resolves to an object containing prelude (a Web Stream of HTML) and postponed (a JSON-serializeable, opaque object).

resumeAndPrerenderToNodeStream parameters

Parameters: reactNode (the React node representing the entire document, expected to have an <html> tag); postponedState (the opaque postpone object returned from a prerender API, loaded from storage like redis or S3); options (optional object with signal for abort control, onBrowserBailout callback for browser() recovery, and onError callback for server errors).

resumeAndPrerenderToNodeStream is Node.js specific

resumeAndPrerenderToNodeStream is specific to Node.js. Environments with Web Streams like Deno and modern edge runtimes should use prerender instead.

resumeAndPrerenderToNodeStream returns Promise with prelude and postponed

On successful rendering, resumeAndPrerenderToNodeStream returns a Promise resolving to an object containing prelude (a Web Stream of HTML that can be piped or read into a string) and postponed (a JSON-serializeable, opaque object for passing to resumeToNodeStream or resumeAndPrerenderToNodeStream if aborted). On failure, the Promise is rejected.

resumeAndPrerenderToNodeStream for resuming prerendered trees

resumeAndPrerenderToNodeStream behaves similarly to prerender but can continue a previously started prerendering process that was aborted, enabling partial pre-rendering workflows.

resumeAndPrerenderToNodeStream signal option for aborting

The optional signal parameter in the options object is an AbortSignal that lets you abort server rendering and render the rest on the client.

resumeAndPrerenderToNodeStream onBrowserBailout callback

The optional onBrowserBailout callback (Canary feature) is called when React recovers from browser() by leaving a Suspense fallback for the browser to replace. It receives an Error describing the browser-only render and an errorInfo object containing componentStack. If a reason was passed to browser, it is available as error.cause.

resumeAndPrerenderToNodeStream onError callback

The optional onError callback fires whenever there is a server error, whether recoverable or not. By default, it only calls console.error. If overridden to log crash reports, make sure to still call console.error.

Give your agent this brain