Skip to content
Tutorials Center
My learning

Topics

React Reference ยท react-dom/server and Static APIs

Bootstrap scripts and server rendering options

Reference for the options of React's server renderers: bootstrapScripts, bootstrapModules, bootstrapScriptContent, importMap, nonce and identifierPrefix.

A server-rendered page is only HTML until the browser loads the JavaScript that hydrates it. The streaming renderers (renderToPipeableStream, renderToReadableStream, prerender and prerenderToNodeStream) can write the script tags for you. You list the files in bootstrapScripts or bootstrapModules, and React places a preload hint in the head and the <script> element at the end of the body, so the code loads without blocking the first paint.

The same options object also carries nonce for a content security policy, identifierPrefix for useId, importMap, bootstrapScriptContent and a few more. This page explains what each one writes. renderToString and renderToStaticMarkup take only identifierPrefix; they do not write script tags.

JSX
const stream = await renderToReadableStream(<App />, {
  bootstrapScripts: ['/assets/main.js'],
  nonce: nonce,
  identifierPrefix: 'app-',
});

Try it

What each option writes

Look at where things land. The preload <link> goes into the head, the executable <script> goes at the end of the body, and the doctype is added because the root is <html>. The nonce is copied onto both elements, and integrity and crossOrigin are copied from the object form.

identifierPrefix with several roots

Without a prefix two roots on the same page would both produce the same first ID. With prefixes they cannot collide. On the client, give hydrateRoot the same identifierPrefix you used on the server, or the IDs will not match.

Syntax

The options are properties of the second argument of the streaming functions.

TypeScript
type BootstrapScript = string | { src: string; integrity?: string; crossOrigin?: string };

type Options = {
  bootstrapScripts?: BootstrapScript[];
  bootstrapModules?: BootstrapScript[];
  bootstrapScriptContent?: string;
  importMap?: { imports?: Record<string, string>; scopes?: Record<string, Record<string, string>> };
  nonce?: string;
  identifierPrefix?: string;
  namespaceURI?: string;
  progressiveChunkSize?: number;
};
Option Description
bootstrapScripts Classic scripts to load. Each gets a low-priority preload link and an async script at the end of the body.
bootstrapModules The same for ES modules: type="module" scripts and modulepreload links.
bootstrapScriptContent Inline JavaScript placed in its own <script> before the external ones. Only pass strings you control.
importMap An object written as <script type="importmap"> at the start of the head, so bare specifiers in your modules resolve.
nonce Added to every script and preload link React writes, including its own streaming helper scripts. Not applied by prerender.
identifierPrefix Prefix for useId values and for the streaming block IDs. Must match hydrateRoot.
namespaceURI Root namespace when you render a fragment of SVG or MathML instead of HTML.
progressiveChunkSize Approximate bytes after which a boundary is streamed separately instead of inlined.

Returns: options produce HTML as described above; they return nothing themselves.

Usage notes

  • Match the client. hydrateRoot(container, <App />, { identifierPrefix }) needs the prefix from the server render; the bundle named in bootstrapScripts is the one that calls hydrateRoot.
  • Use integrity for files from a CDN, and crossOrigin: 'anonymous' with it, so the browser can check the hash.
  • A nonce must be unique per response. Reusing a nonce defeats the point of a content security policy. Generate it per request and send the same value in the Content-Security-Policy header.
  • bootstrapScriptContent is for tiny globals such as server-provided configuration. Serialize data with a safe JSON encoder that escapes < as <, otherwise a string containing </script> ends the element early.
  • Script order follows the array. Because the scripts are async, execution order between them is not guaranteed; load one entry file and import the rest.
  • The scripts come from the root document. When you render only a fragment (not <html>), they are written around your output, which is rarely what you want.
  • renderToString accepts only identifierPrefix; to ship scripts with it, write the tags yourself.
  • Static builds cannot use a nonce, since a file is generated before any request exists.