renderToString does not support streaming
renderToString returns an HTML string immediately and does not support streaming or waiting for data. It returns a complete string all at once.
React · API reference · all subjects
react-dom/server
104 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
renderToString limited Suspense support
renderToString has limited Suspense support. If a component suspends, renderToString immediately sends its fallback as HTML and does not wait for the content to resolve. The content will not appear until the client code loads.
renderToString works in browser but not recommended for client code
renderToString works in the browser but using it in client code is not recommended because it unnecessarily increases bundle size. If you need to render a component to HTML in the browser, use createRoot and read HTML from the DOM instead.
renderToString signature and basic usage
renderToString renders a React tree to an HTML string. The signature is: const html = renderToString(reactNode, options?). It takes a React node (such as a JSX element like <App />) and optional options object, and returns an HTML string.
renderToString server-side example
Example of using renderToString on the server: import { renderToString } from 'react-dom/server'; app.use('/', (request, response) => { const html = renderToString(<App />); response.send(html); }); This produces the initial non-interactive HTML output of React components. On the client, call hydrateRoot to hydrate that server-generated HTML and make it interactive.
renderToString client-side anti-pattern and alternative
Anti-pattern: importing renderToString on the client unnecessarily increases bundle size. Instead, use createRoot and read HTML from the DOM: import { createRoot } from 'react-dom/client'; import { flushSync } from 'react-dom'; const div = document.createElement('div'); const root = createRoot(div); flushSync(() => { root.render(<MyIcon />); }); console.log(div.innerHTML);. The flushSync call ensures the DOM is updated before reading its innerHTML property.
renderToString streaming alternatives
renderToString does not support streaming. For Node.js, use renderToPipeableStream. For Deno or modern edge runtimes with Web Streams API, use renderToReadableStream. These alternatives can stream content in chunks as it resolves on the server.
renderToString static prerender alternatives
renderToString does not support waiting for data to load for static HTML generation. For Node.js, use prerenderToNodeStream. For Deno or modern edge runtimes with Web Streams API, use prerender. These alternatives can wait for all content to resolve before generating static HTML.
resume stream allReady property
The returned stream has an allReady property that is a Promise resolving when all rendering is complete. You can await stream.allReady before returning a response for crawlers and static generation, but you won't get any progressive loading and the stream will contain the final HTML.
resume function signature
The resume function is called with the signature: const stream = await resume(reactNode, postponedState, options?). It streams a pre-rendered React tree to a Readable Web Stream.
resume reactNode parameter
The reactNode parameter is the React node you called prerender with, such as a JSX element like <App />. It is expected to represent the entire document, so the App component should render the <html> tag.
resume postponedState parameter
The postponedState parameter is the opaque postpone object returned from a prerender API, loaded from wherever it was stored (for example, redis, a file, or S3).
resume options nonce parameter
The options.nonce is an optional string parameter that allows scripts for script-src Content-Security-Policy.
resume options signal parameter
The options.signal is an optional AbortSignal that lets you abort server rendering and render the rest on the client.
resume options onError parameter
The options.onError is an optional callback that fires whenever there is a server error, whether recoverable or not. By default, this only calls console.error. If you override it to log crash reports, make sure that you still call console.error.
resume return value
The resume function returns a Promise. If resume successfully produced a shell, that Promise resolves to a Readable Web Stream that can be piped to a Writable Web Stream. If an error happens in the shell, the Promise rejects with that error.
resume does not accept bootstrapScripts options
resume does not accept options for bootstrapScripts, bootstrapScriptContent, or bootstrapModules. Instead, you need to pass these options to the prerender call that generates the postponedState. You can also inject bootstrap content into the writable stream manually.
resume does not accept identifierPrefix option
resume does not accept identifierPrefix since the prefix needs to be the same in both prerender and resume.
resume nonce caveat with prerender
Since nonce cannot be provided to prerender, you should only provide nonce to resume if you are not providing scripts to prerender.
resume re-renders from root until finding incomplete component
resume re-renders from the root until it finds a component that was not fully pre-rendered. Only fully prerendered components (the component and its children finished prerendering) are skipped entirely.
resume depends on Web Streams API
The resume API depends on Web Streams. For Node.js, use resumeToNodeStream instead.
resume example with prerender workflow
Example showing resume usage in a three-layer workflow: (1) prerender with AbortController to generate prelude and postponed state, flush prelude to frame, (2) wait for data fetching to complete, resolve cookies, call resume with <App /> and postponed state, flush resume stream to frame, (3) wait and then hydrateRoot to enable interactivity. The example shows how Header can be prerendered and Main can be resumed after data becomes available.
resumeToPipeableStream does not accept bootstrapScripts options
resumeToPipeableStream does not accept options for `bootstrapScripts`, `bootstrapScriptContent`, or `bootstrapModules`. Instead, you need to pass these options to the `prerender` call that generates the `postponedState`. You can also inject bootstrap content into the writable stream manually.
resumeToPipeableStream does not accept identifierPrefix
resumeToPipeableStream does not accept `identifierPrefix` since the prefix needs to be the same in both `prerender` and `resumeToPipeableStream`.
resumeToPipeableStream nonce caveat
Since `nonce` cannot be provided to prerender, you should only provide `nonce` to `resumeToPipeableStream` if you're not providing scripts to prerender.
resumeToPipeableStream re-rendering behavior
resumeToPipeableStream re-renders from the root until it finds a component that was not fully pre-rendered. Only fully prerendered components (the component and its children finished prerendering) are skipped entirely.
resumeToPipeableStream function signature
resumeToPipeableStream is called with `const {pipe, abort} = await resumeToPipeableStream(reactNode, postponedState, options?)`. It streams a pre-rendered React tree to a pipeable Node.js Stream. This API is specific to Node.js; environments with Web Streams like Deno and modern edge runtimes should use `resume` instead.
resumeToPipeableStream usage example
Example showing how to use resumeToPipeableStream in a request handler: ```js import { resume } from 'react-dom/server'; import {getPostponedState} from './storage'; async function handler(request, response) { const postponed = await getPostponedState(request); const {pipe} = resumeToPipeableStream(<App />, postponed, { onShellReady: () => { pipe(response); } }); } ```
resumeToPipeableStream parameters
resumeToPipeableStream accepts three parameters: (1) `reactNode` - the React node called with `prerender`, typically a JSX element like `<App />` representing the entire document with an `<html>` tag; (2) `postponedState` - the opaque postpone object returned from a prerender API, loaded from storage like redis, a file, or S3; (3) `options` (optional) - an object with streaming options.
resumeToPipeableStream options object
The options object for resumeToPipeableStream has these optional fields: `nonce` (string) - a nonce to allow scripts for script-src Content-Security-Policy; `signal` (AbortSignal) - lets you abort server rendering and render the rest on the client; `onError` (callback) - fires on any server error (recoverable or not), defaults to console.error; `onShellReady` (callback) - fires after the shell finishes, call `pipe` here to start streaming; `onShellError` (callback) - fires if there was an error rendering the shell, receives the error as an argument.
resumeToPipeableStream return value
resumeToPipeableStream returns an object with two methods: (1) `pipe` - outputs the HTML into a provided Writable Node.js Stream, call in `onShellReady` to enable streaming or in `onAllReady` for crawlers and static generation; (2) `abort` - lets you abort server rendering and render the rest on the client.
prerender uses Web Streams API
prerender renders using the Web Streams API. For Node.js environments that do not support Web Streams, use prerenderToNodeStream instead.
prerender difference from renderToReadableStream
prerender waits for the entire app to finish rendering, including all Suspense boundaries, before resolving. It is designed for static site generation (SSG) ahead of time and does not support streaming content as it loads. For streaming content as it loads, use renderToReadableStream instead.
prerender with assetMap example
Example showing how to pass asset URLs to prerender and the client: Server: ```js const assetMap = { 'styles.css': '/styles.123456.css', 'main.js': '/main.123456.js' }; async function handler(request) { const {prelude} = await prerender(<App assetMap={assetMap} />, { bootstrapScriptContent: `window.assetMap = ${JSON.stringify(assetMap)};`, bootstrapScripts: [assetMap['/main.js']], }); return new Response(prelude, { headers: { 'content-type': 'text/html' }, }); } ``` Client: ```js import { hydrateRoot } from 'react-dom/client'; import App from './App.js'; hydrateRoot(document, <App assetMap={window.assetMap} />); ``` Both server and client render App with the same assetMap prop to avoid hydration errors.
prerender root component structure
The root component passed to prerender should return the entire document including the <html> tag. It typically includes head metadata, stylesheets, and body content with child components.
prerender function signature and overview
prerender renders a React tree to a static HTML string using a Web Stream. The signature is: const {prelude, postponed} = await prerender(reactNode, options?). It is used for static server-side generation (SSG) and waits for all data to load before resolving, making it suitable for generating static HTML for a full page including data fetched with Suspense. The API depends on Web Streams; for Node.js use prerenderToNodeStream instead.
prerender parameters
prerender accepts two parameters: (1) reactNode - a React node to render, expected to represent the entire document including the root <html> tag; (2) options (optional) - an object with static generation options. The options object supports: bootstrapScriptContent (optional string placed in inline <script> tag), bootstrapScripts (optional array of string URLs for <script> tags), bootstrapModules (optional, emits <script type="module"> instead), identifierPrefix (optional string prefix for IDs generated by useId, must match hydrateRoot prefix), namespaceURI (optional root namespace URI, defaults to regular HTML, pass 'http://www.w3.org/2000/svg' for SVG or 'http://www.w3.org/1998/Math/MathML' for MathML), onError (optional callback for server errors), progressiveChunkSize (optional number of bytes in a chunk), signal (optional AbortSignal for aborting prerendering).
prerender return value
prerender returns a Promise. On successful rendering, it resolves to an object containing: prelude (a Web Stream of HTML that can be sent in chunks or read entirely into a string) and postponed (a JSON-serializable opaque object that can be passed to resume if prerender did not finish, otherwise null if prelude contains all content). If rendering fails, the Promise is rejected.
prerender caveat: nonce not available
The nonce option is not available when prerendering. Nonces must be unique per request, and using nonces in prerendered content would be inappropriate and insecure for CSP-secured applications.
prerender example rendering to stream
Example showing how to render a React tree to a Readable Web Stream: ```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' }, }); } ``` The root component should return the entire document including the <html> tag. React will inject the doctype and bootstrap <script> tags into the resulting HTML stream. On the client, call hydrateRoot(document, <App />) to make the server-generated HTML interactive.
prerender example rendering to string
Example showing how to render a React tree to a static HTML string by reading the stream: ```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'); } } ``` This produces the initial non-interactive HTML output. Call hydrateRoot on the client to make it interactive.
prerender waits for all Suspense boundaries
prerender waits for all data to load before finishing static HTML generation and resolving. 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 abort example
Example showing how to abort prerendering after a timeout: ```js async function renderToString() { const controller = new AbortController(); setTimeout(() => { controller.abort() }, 10000); try { const {prelude} = await prerender(<App />, { signal: controller.signal, }); // prelude will contain all HTML prerendered before abort } } ``` Any Suspense boundaries with incomplete children will be included in the prelude in the fallback state. This enables partial prerendering with resume or resumeAndPrerender.
useId identifierPrefix must match on server and client
When rendering multiple independent React apps on the same page with server rendering, the identifierPrefix you pass to hydrateRoot on the client side must be the same as the identifierPrefix you pass to server APIs like renderToPipeableStream. You do not need to pass identifierPrefix if you only have one React app on the page.