Scribd
Upload
3 views

prerenderToNodeStream – React

The document provides an API reference for the `prerenderToNodeStream` function in React, which allows rendering a React tree to static HTML using a Node.js stream. It details usage, parameters, and return values, emphasizing that this API is suitable for static server-side generation and waits for all data to load before resolving. Additionally, it includes troubleshooting tips and examples for implementing the function in a server environment.

Uploaded by

dungeon.dad87
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
3 views

prerenderToNodeStream – React

The document provides an API reference for the `prerenderToNodeStream` function in React, which allows rendering a React tree to static HTML using a Node.js stream. It details usage, parameters, and return values, emphasizing that this API is suitable for static server-side generation and waits for all data to load before resolving. Additionally, it includes troubleshooting tips and examples for implementing the function in a server environment.

Uploaded by

dungeon.dad87
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 9

20/02/2025, 19:18 prerenderToNodeStream – React

v19

API REFERENCE STATIC APIS

prerenderToNodeStream
prerenderToNodeStream renders a React tree to a static HTML
string using a Node.js Stream..

const {prelude} = await prerenderToNodeStream(reactNode, option

Reference

prerenderToNodeStream(reactNode, options?)

Usage

Rendering a React tree to a stream of static HTML


Rendering a React tree to a string of static HTML
Waiting for all data to load

Troubleshooting

My stream doesn’t start until the entire app is rendered

Note

This API is specific to Node.js. Environments with Web Streams, like


Deno and modern edge runtimes, should use prerender instead.

Reference

https://react.dev/reference/react-dom/static/prerenderToNodeStream 1/9
20/02/2025, 19:18 prerenderToNodeStream – React

prerenderToNodeStream(reactNode, options?)

Call prerenderToNodeStream to render your app to static HTML.

import { prerenderToNodeStream } from 'react-dom/static';

// The route handler syntax depends on your backend framework


app.use('/', async (request, response) => {
const { prelude } = await prerenderToNodeStream(<App />, {
bootstrapScripts: ['/main.js'],
});

response.setHeader('Content-Type', 'text/plain');
prelude.pipe(response);
});

On the client, call hydrateRoot to make the server-generated HTML


interactive.

See more examples below.

Parameters

reactNode : A React node you want to render to HTML. For example, a


JSX node like <App /> . It is expected to represent the entire document,
so the App component should render the <html> tag.

optional options : An object with static generation options.

optional bootstrapScriptContent : If specified, this string will be


placed in an inline <script> tag.
optional bootstrapScripts : An array of string URLs for the <script>
tags to emit on the page. Use this to include the <script> that calls
hydrateRoot . Omit it if you don’t want to run React on the client at all.

optional bootstrapModules : Like bootstrapScripts , but emits


<script type="module"> instead.

optional identifierPrefix : A string prefix React uses for IDs


generated by useId . Useful to avoid conflicts when using multiple

https://react.dev/reference/react-dom/static/prerenderToNodeStream 2/9
20/02/2025, 19:18 prerenderToNodeStream – React

roots on the same page. Must be the same prefix as passed to


hydrateRoot .

optional namespaceURI : A string with the root namespace URI for the
stream. Defaults to regular HTML. Pass
'http://www.w3.org/2000/svg' for SVG or
'http://www.w3.org/1998/Math/MathML' for MathML.

optional onError : A 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 . You can also use it to adjust the status code before
the shell is emitted.
optional progressiveChunkSize : The number of bytes in a chunk. Read
more about the default heuristic.
optional signal : An abort signal that lets you abort server rendering
and render the rest on the client.

Returns

prerenderToNodeStream returns a Promise:

If rendering the is successful, the Promise will resolve to an object


containing:

prelude : a Node.js Stream. of HTML. You can use this stream to send
a response in chunks, or you can read the entire stream into a string.

If rendering fails, the Promise will be rejected. Use this to output a fallback
shell.

Note

When should I use prerenderToNodeStream ?

The static prerenderToNodeStream API is used for static server-side


generation (SSG). Unlike renderToString , prerenderToNodeStream
waits for all data to load before resolving. This makes it suitable for

https://react.dev/reference/react-dom/static/prerenderToNodeStream 3/9
20/02/2025, 19:18 prerenderToNodeStream – React

generating static HTML for a full page, including data that needs to
be fetched using Suspense. To stream content as it loads, use a
streaming server-side render (SSR) API like
renderToReadableStream.

Usage

Rendering a React tree to a stream of static HTML

Call prerenderToNodeStream to render your React tree to static HTML into a


Node.js Stream.:

import { prerenderToNodeStream } from 'react-dom/static';

// The route handler syntax depends on your backend framework


app.use('/', async (request, response) => {
const { prelude } = await prerenderToNodeStream( <App /> , {
bootstrapScripts: ['/main.js'] ,
});

response.setHeader('Content-Type', 'text/plain');
prelude.pipe(response);
});

Along with the root component , you need to provide a list of bootstrap
<script> paths . Your root component should return the entire document

including the root <html> tag.

For example, it might look like this:

export default function App () {


return (
<html>

https://react.dev/reference/react-dom/static/prerenderToNodeStream 4/9
20/02/2025, 19:18 prerenderToNodeStream – React

<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale
<link rel="stylesheet" href="/styles.css"></link>
<title>My app</title>
</head>
<body>
<Router />
</body>
</html>
);
}

React will inject the doctype and your bootstrap <script> tags into the
resulting HTML stream:

<!DOCTYPE html>
<html>
<!-- ... HTML from your components ... -->
</html>
<script src=" /main.js " async=""></script>

On the client, your bootstrap script should hydrate the entire document with
a call to hydrateRoot :

import { hydrateRoot } from 'react-dom/client';


import App from './App.js';

hydrateRoot(document, <App /> );

This will attach event listeners to the static server-generated HTML and
make it interactive.

DEEP DIVE

https://react.dev/reference/react-dom/static/prerenderToNodeStream 5/9
20/02/2025, 19:18 prerenderToNodeStream – React

Reading CSS and JS asset paths from the build output

Show Details

Rendering a React tree to a string of static HTML

Call prerenderToNodeStream to render your app to a static HTML string:

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);
});
}

This will produce the initial non-interactive HTML output of your React
components. On the client, you will need to call hydrateRoot to hydrate that
server-generated HTML and make it interactive.

Waiting for all data to load

prerenderToNodeStream waits for all data to load before finishing the static

HTML generation and resolving. For example, consider a profile page that

https://react.dev/reference/react-dom/static/prerenderToNodeStream 6/9
20/02/2025, 19:18 prerenderToNodeStream – React

shows a cover, a sidebar with friends and photos, and a list of posts:

function ProfilePage() {
return (
<ProfileLayout>
<ProfileCover />
<Sidebar>
<Friends />
<Photos />
</Sidebar>
<Suspense fallback={<PostsGlimmer />}>
<Posts />
</Suspense>
</ProfileLayout>
);
}

Imagine that <Posts /> needs to load some data, which takes some time.
Ideally, you’d want wait for the posts to finish so it’s included in the HTML. To
do this, you can use Suspense to suspend on the data, and
prerenderToNodeStream will wait for the suspended content to finish before

resolving to the static HTML.

Note

Only Suspense-enabled data sources will activate the Suspense


component. They include:

Data fetching with Suspense-enabled frameworks like Relay and


Next.js
Lazy-loading component code with lazy
Reading the value of a Promise with use

Suspense does not detect when data is fetched inside an Effect or


event handler.

https://react.dev/reference/react-dom/static/prerenderToNodeStream 7/9
20/02/2025, 19:18 prerenderToNodeStream – React

The exact way you would load data in the Posts component above
depends on your framework. If you use a Suspense-enabled
framework, you’ll find the details in its data fetching documentation.

Suspense-enabled data fetching without the use of an opinionated


framework is not yet supported. The requirements for implementing
a Suspense-enabled data source are unstable and undocumented.
An official API for integrating data sources with Suspense will be
released in a future version of React.

Troubleshooting

My stream doesn’t start until the entire app is


rendered

The prerenderToNodeStream response waits for the entire app to finish


rendering, including waiting for all Suspense boundaries to resolve, before
resolving. It is designed for static site generation (SSG) ahead of time and
does not support streaming more content as it loads.

To stream content as it loads, use a streaming server render API like


renderToPipeableStream.

PREVIOUS

prerender

Copyright © Meta Platforms, Inc

https://react.dev/reference/react-dom/static/prerenderToNodeStream 8/9
20/02/2025, 19:18 prerenderToNodeStream – React

uwu?

Learn React API Reference

Quick Start React APIs

Installation React DOM APIs

Describing the UI

Adding Interactivity

Managing State

Escape Hatches

Community More

Code of Conduct Blog

Meet the Team React Native

Docs Contributors Privacy

Acknowledgements Terms

https://react.dev/reference/react-dom/static/prerenderToNodeStream 9/9

You might also like