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.
const stream = await renderToReadableStream(<App />, { bootstrapScripts: ['/assets/main.js'], nonce: nonce, identifierPrefix: 'app-', });
Try it
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.
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.
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 inbootstrapScriptsis the one that callshydrateRoot. - Use
integrityfor files from a CDN, andcrossOrigin: '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-Policyheader. bootstrapScriptContentis 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. renderToStringaccepts onlyidentifierPrefix; to ship scripts with it, write the tags yourself.- Static builds cannot use a nonce, since a file is generated before any request exists.