20/02/2025, 19:18 prerender – React
v19
API REFERENCE STATIC APIS
prerender
prerender renders a React tree to a static HTML string using a
Web Stream.
const {prelude} = await prerender(reactNode, options?)
Reference
prerender(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 depends on Web Streams. For Node.js, use
prerenderToNodeStream instead.
Reference
https://react.dev/reference/react-dom/static/prerender 1/9
20/02/2025, 19:18 prerender – React
prerender(reactNode, options?)
Call prerender to render your app to static HTML.
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' },
});
}
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/prerender 2/9
20/02/2025, 19:18 prerender – 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
prerender returns a Promise:
If rendering the is successful, the Promise will resolve to an object
containing:
prelude : a Web 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 prerender ?
The static prerender API 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
https://react.dev/reference/react-dom/static/prerender 3/9
20/02/2025, 19:18 prerender – React
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 prerender to render your React tree to static HTML into a Readable
Web Stream::
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' },
});
}
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>
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale
https://react.dev/reference/react-dom/static/prerender 4/9
20/02/2025, 19:18 prerender – React
<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
Reading CSS and JS asset paths from the build output
https://react.dev/reference/react-dom/static/prerender 5/9
20/02/2025, 19:18 prerender – React
Show Details
Rendering a React tree to a string of static HTML
Call prerender to render your app to a static HTML string:
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 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
prerender waits for all data to load before finishing the static HTML
generation and resolving. For example, consider a profile page that shows a
cover, a sidebar with friends and photos, and a list of posts:
https://react.dev/reference/react-dom/static/prerender 6/9
20/02/2025, 19:18 prerender – React
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 prerender 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.
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.
https://react.dev/reference/react-dom/static/prerender 7/9
20/02/2025, 19:18 prerender – React
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 prerender 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
renderToReadableStream.
PREVIOUS
Static APIs
NEXT
prerenderToNodeStream
Copyright © Meta Platforms, Inc
https://react.dev/reference/react-dom/static/prerender 8/9
20/02/2025, 19:18 prerender – 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/prerender 9/9
