Call `createRoot` to create a React root for displaying content inside a browser DOM element.
Call `createRoot` to create a React root for displaying content inside a browser DOM element.
@ -256,10 +256,10 @@ An app fully built with React will usually only have one `createRoot` call for i
* `domNode`: A [DOM element.](https://developer.mozilla.org/en-US/docs/Web/API/Element) React will create a root for this DOM element and allow you to call functions on the root, such as `render` to display rendered React content.
* `domNode`: A [DOM element.](https://developer.mozilla.org/en-US/docs/Web/API/Element) React will create a root for this DOM element and allow you to call functions on the root, such as `render` to display rendered React content.
* **optional**`options`: A object contain options for this React root.
* **optional**`options`: An object with options for this React root.
* `onRecoverableError`: optional callback called when React automatically recovers from errors.
* **optional** `onRecoverableError`: Callback called when React automatically recovers from errors.
* `identifierPrefix`: optional prefix React uses for IDs generated by [`useId`.](/apis/react/useId) Useful to avoid conflicts when using multiple roots on the same page.
* **optional** `identifierPrefix`: A string prefix React uses for IDs generated by [`useId`.](/apis/react/useId) Useful to avoid conflicts when using multiple roots on the same page.
@ -44,7 +44,7 @@ To hydrate your app, React will "attach" your components' logic to the initial g
```js index.js active
```js index.js active
import './styles.css';
import './styles.css';
import {hydrateRoot} from 'react-dom/client';
import {hydrateRoot} from 'react-dom/client';
import App from './App.js';
import App from './App.js';
hydrateRoot(
hydrateRoot(
@ -120,7 +120,7 @@ function App() {
To hydrate the entire document, pass the [`document`](https://developer.mozilla.org/en-US/docs/Web/API/Window/document) global as the first argument to `hydrateRoot`:
To hydrate the entire document, pass the [`document`](https://developer.mozilla.org/en-US/docs/Web/API/Window/document) global as the first argument to `hydrateRoot`:
```js {5}
```js {5}
import {hydrateRoot} from 'react-dom/client';
import {hydrateRoot} from 'react-dom/client';
import App from './App.js';
import App from './App.js';
hydrateRoot(
hydrateRoot(
@ -148,7 +148,7 @@ If you call `root.render` at some point after hydration, and the component tree
```
```
```js index.js active
```js index.js active
import {hydrateRoot} from 'react-dom/client';
import {hydrateRoot} from 'react-dom/client';
import './styles.css';
import './styles.css';
import App from './App.js';
import App from './App.js';
@ -183,7 +183,7 @@ It is uncommon to call [`root.render`](#root-render) on a hydrated root. Usually
Call `hydrateRoot` to “attach” React to existing HTML that was already rendered by React in a server environment.
Call `hydrateRoot` to “attach” React to existing HTML that was already rendered by React in a server environment.
@ -202,10 +202,11 @@ React will attach to the HTML that exists inside the `domNode`, and take over ma
* `reactNode`: The "React node" used to render the existing HTML. This will usually be a piece of JSX like `<App />` which was rendered with a `ReactDOM Server` method such as `renderToPipeableStream(<App />)`.
* `reactNode`: The "React node" used to render the existing HTML. This will usually be a piece of JSX like `<App />` which was rendered with a `ReactDOM Server` method such as `renderToPipeableStream(<App />)`.
* **optional**`options`: A object contain options for this React root.
* **optional**`options`: An object with options for this React root.
* `onRecoverableError`: optional callback called when React automatically recovers from errors.
* **optional** `onRecoverableError`: Callback called when React automatically recovers from errors.
* `identifierPrefix`: optional prefix React uses for IDs generated by [`useId`.](/apis/react/useId) Useful to avoid conflicts when using multiple roots on the same page. Must be the same prefix as used on the server.
* **optional** `identifierPrefix`: A string prefix React uses for IDs generated by [`useId`.](/apis/react/useId) Useful to avoid conflicts when using multiple roots on the same page. Must be the same prefix as used on the server.
### Rendering a React tree as HTML to a Node.js Readable stream {/*rendering-a-react-tree-as-html-to-a-nodejs-readable-stream*/}
### Rendering a React tree as HTML to a Node.js Readable Stream {/*rendering-a-react-tree-as-html-to-a-nodejs-readable-stream*/}
<Deprecated>
<Deprecated>
@ -32,9 +32,11 @@ This API will be removed in a future major version of React. Use [`renderToPipea
</Deprecated>
</Deprecated>
Call `renderToNodeStream` to get a [Node.js Readable stream](https://nodejs.org/api/stream.html#readable-streams) which you can pipe to your server response:
Call `renderToNodeStream` to get a [Node.js Readable Stream](https://nodejs.org/api/stream.html#readable-streams) which you can pipe to your server response:
```js {5-6}
import { renderToNodeStream } from 'react-dom/server';
```js {3-4}
// The route handler syntax depends on your backend framework
// The route handler syntax depends on your backend framework
app.use('/', (request, response) => {
app.use('/', (request, response) => {
const stream = renderToNodeStream(<App/>);
const stream = renderToNodeStream(<App/>);
@ -56,7 +58,7 @@ This API will be removed in a future major version of React. Use [`renderToPipea
</Deprecated>
</Deprecated>
On the server, call `renderToNodeStream` to get a [Node.js Readable stream](https://nodejs.org/api/stream.html#readable-streams) which you can pipe into the response.
On the server, call `renderToNodeStream` to get a [Node.js Readable Stream](https://nodejs.org/api/stream.html#readable-streams) which you can pipe into the response.
```js
```js
const stream = renderToNodeStream(<App/>);
const stream = renderToNodeStream(<App/>);
@ -71,7 +73,7 @@ On the client, call [`hydrateRoot`](/apis/react-dom/client/hydrateRoot) to make
#### Returns {/*returns*/}
#### Returns {/*returns*/}
A [Node.js Readable stream](https://nodejs.org/api/stream.html#readable-streams) that outputs an HTML string.
A [Node.js Readable Stream](https://nodejs.org/api/stream.html#readable-streams) that outputs an HTML string.
This section is incomplete, please see the old docs for [renderToPipeableStream.](https://reactjs.org/docs/react-dom-server.html#rendertopipeablestream)
`renderToPipeableStream` renders a React tree to a pipeable [Node.js Stream.](https://nodejs.org/api/stream.html)
### Rendering a React tree as HTML to a Node.js Stream {/*rendering-a-react-tree-as-html-to-a-nodejs-stream*/}
Call `renderToPipeableStream` to render your React tree as HTML into a [Node.js Stream:](https://nodejs.org/api/stream.html#writable-streams)
```js [[1, 5, "<App/>"], [2, 6, "['/main.js']"]]
import { renderToPipeableStream } from 'react-dom/server';
// The route handler syntax depends on your backend framework
app.use('/', (request, response) => {
const { pipe } = renderToPipeableStream(<App/>, {
bootstrapScripts: ['/main.js'],
onShellReady() {
pipe(response);
}
});
});
```
Along with the <CodeStepstep={1}>root component</CodeStep>, you need to provide a list of <CodeStepstep={2}>boostrap `<script>` paths</CodeStep>. Your root component should return **the entire document including the root `<html>` tag.** For example, it might look like this:
```js [[1, 1, "App"]]
export default function App() {
return (
<html>
<head>
<title>My app</title>
<linkrel="stylesheet"href="/styles.css"></link>
</head>
<body>
<Router/>
</body>
</html>
);
}
```
React will automatically inject the [doctype](https://developer.mozilla.org/en-US/docs/Glossary/Doctype) and your <CodeStepstep={2}>bootstrap `<script>` tags</CodeStep> into the resulting HTML stream:
```html [[2, 5, "/main.js"]]
<!DOCTYPE html>
<html>
<!-- ... HTML from your components ... -->
</html>
<scriptsrc="/main.js"async=""></script>
```
On the client, your bootstrap script should [hydrate the entire `document` with a call to `hydrateRoot`:](/apis/react-dom/client/hydrateRoot#hydrating-an-entire-document)
```js [[1, 4, "<App/>"]]
import {hydrateRoot} from 'react-dom/client';
import App from './App.js';
hydrateRoot(document, <App/>);
```
This will attach event listeners to the server-generated HTML and make it interactive.
<DeepDive>
#### Reading CSS and JS asset paths from the build output {/*reading-css-and-js-asset-paths-from-the-build-output*/}
The final asset URLs (like JavaScript and CSS files) are often hashed after the build. For example, instead of `styles.css` you might end up with `styles.123456.css`. Hashing static asset filenames guarantees that every distinct build of the same asset will have a different filename. This is useful because it lets you safely enable long-term caching for static assets: a file with a certain name would never change content.
However, if you don't know the asset URLs until after the build, there's no way for you to put them in the source code. For example, hardcoding `"/styles.css"` into JSX like earlier wouldn't work. To keep them out of your source code, your root component can read the real filenames from a map passed as a prop:
Since your server is now rendering `<App assetMap={assetMap} />`, you need to render it with `assetMap` on the client too to avoid hydration errors. You can serialize and pass `assetMap` to the client like this:
```js {9-10}
// You'd need to get this JSON from your build tooling.
In the example above, the `bootstrapScriptContents` option adds an extra inline `<script>` tag that sets the global `window.assetMap` variable on the client. This lets the client code read the same `assetMap`:
Both client and server render `App` with the same `assetMap` prop, so there are no hydration errors.
</DeepDive>
---
### Streaming more content as it loads {/*streaming-more-content-as-it-loads*/}
Streaming allows the user to start seeing the content even before all the data has loaded on the server. For example, consider a profile page that shows a cover, a sidebar with friends and photos, and a list of posts:
```js
```js
renderToPipeableStream(element, options)
function ProfilePage() {
return (
<ProfileLayout>
<ProfileCover/>
<Sidebar>
<Friends/>
<Photos/>
</Sidebar>
<Posts/>
</ProfileLayout>
);
}
```
```
</Intro>
Imagine that loading data for `<Posts />` takes some time. Ideally, you'd want to show the rest of the profile page content to the user without waiting for the posts. To do this, [wrap `Posts` in a `<Suspense>` boundary:](/apis/react/Suspense#displaying-a-fallback-while-content-is-loading)
<InlineToc/>
```js {9,11}
function ProfilePage() {
return (
<ProfileLayout>
<ProfileCover/>
<Sidebar>
<Friends/>
<Photos/>
</Sidebar>
<Suspensefallback={<PostsGlimmer/>}>
<Posts/>
</Suspense>
</ProfileLayout>
);
}
```
This way, you tell React to start streaming the HTML before `Posts` loads its data. React will send the HTML for the loading fallback (`PostsGlimmer`) first, and then, when `Posts` finishes loading its data, React will send the remaining HTML along with an inline `<script>` tag that replaces the loading fallback with that HTML. From the user's perspective, the page will first appear with the `PostsGlimmer`, and then it will be replaced by the `Posts`.
You can further [nest `<Suspense>` boundaries](/apis/react/Suspense#revealing-nested-content-as-it-loads) to create a more granular loading sequence:
```js {5,13}
function ProfilePage() {
return (
<ProfileLayout>
<ProfileCover/>
<Suspensefallback={<BigSpinner/>}>
<Sidebar>
<Friends/>
<Photos/>
</Sidebar>
<Suspensefallback={<PostsGlimmer/>}>
<Posts/>
</Suspense>
</Suspense>
</ProfileLayout>
);
}
```
In this example, React can start streaming the page even earlier. Only `ProfileLayout` and `ProfileCover` must finish rendering first because they are not wrapped in any `<Suspense>` boundary. However, if `Sidebar`, `Friends`, or `Photos` need to load some data, React will send the HTML for the `BigSpinner` fallback instead. Then, as enough data becomes available, more content will continue to be revealed until all of it becomes visible.
Streaming does not need to wait for React itself to load in the browser, or for your app to become interactive. The HTML content from the server will get progressively revealed before any of the `<script>` tags have loaded.
[Read more about how streaming HTML works.](https://github.com/reactwg/react-18/discussions/37)
<Note>
**Only Suspense-enabled data sources will activate the Suspense component.** They include:
- Data fetching with Suspense-enabled frameworks like [Relay](https://relay.dev/docs/guided-tour/rendering/loading-states/) and [Next.js](https://nextjs.org/docs/advanced-features/react-18)
- Lazy-loading component code with [`lazy`](/apis/react/lazy)
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.
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.
</Note>
---
### Specifying what goes into the shell {/*specifying-what-goes-into-the-shell*/}
The part of your app outside of any `<Suspense>` boundaries is called *the shell:*
```js {3-5,13,14}
function ProfilePage() {
return (
<ProfileLayout>
<ProfileCover/>
<Suspensefallback={<BigSpinner/>}>
<Sidebar>
<Friends/>
<Photos/>
</Sidebar>
<Suspensefallback={<PostsGlimmer/>}>
<Posts/>
</Suspense>
</Suspense>
</ProfileLayout>
);
}
```
It determines the earliest loading state that the user may see:
```js {3-5,13
<ProfileLayout>
<ProfileCover/>
<BigSpinner/>
</ProfileLayout>
```
If you wrap the whole app into a `<Suspense>` boundary at the root, the shell will only contain that spinner. However, that's not a pleasant user experience because seeing a big spinner on the screen can feel slower and more annoying than waiting a bit more and seeing the real layout. This is why usually you'll want to place the `<Suspense>` boundaries so that the shell feels *minimal but complete*--like a skeleton of the entire page layout.
The `onShellReady` callback fires when the entire shell has been rendered. Usually, you'll start streaming then:
```js {3-5}
const { pipe } = renderToPipeableStream(<App/>, {
bootstrapScripts: ['/main.js'],
onShellReady() {
pipe(response);
}
});
```
By the time `onShellReady` fires, components in nested `<Suspense>` boundaries might still be loading data.
---
### Logging crashes on the server {/*logging-crashes-on-the-server*/}
By default, all errors on the server are logged to console. You can override this behavior to log crash reports:
```js {6-9}
const { pipe } = renderToPipeableStream(<App/>, {
bootstrapScripts: ['/main.js'],
onShellReady() {
pipe(response);
},
onError(error) {
console.error(error);
logServerCrashReport(error);
}
});
```
If you provide a custom `onError` implementation, don't forget to also log errors to the console like above.
---
### Recovering from errors inside the shell {/*recovering-from-errors-inside-the-shell*/}
In this example, the shell contains `ProfileLayout`, `ProfileCover`, and `PostsGlimmer`:
```js {3-5,7-8}
function ProfilePage() {
return (
<ProfileLayout>
<ProfileCover/>
<Suspensefallback={<PostsGlimmer/>}>
<Posts/>
</Suspense>
</ProfileLayout>
);
}
```
If an error occurs while rendering those components, React won't have any meaningful HTML to send to the client. Override `onShellError` to send a fallback HTML that doesn't rely on server rendering as the last resort:
```js {6-9}
const { pipe } = renderToPipeableStream(<App/>, {
bootstrapScripts: ['/main.js'],
onShellReady() {
pipe(response);
},
onShellError(error) {
response.statusCode = 500;
response.send('<h1>Something went wrong</h1>');
},
onError(error) {
console.error(error);
logServerCrashReport(error);
}
});
```
If there is an error while generating the shell, both `onError` and `onShellError` will fire. Use `onError` for error reporting and use `onShellError` to send the fallback HTML document. Your fallback HTML does not have to be an error page. For example, you can include an alternative shell that tries to render your app on the client only.
---
### Recovering from errors outside the shell {/*recovering-from-errors-outside-the-shell*/}
In this example, the `<Posts />` component is wrapped in `<Suspense>` so it is *not* a part of the shell:
```js {6}
function ProfilePage() {
return (
<ProfileLayout>
<ProfileCover/>
<Suspensefallback={<PostsGlimmer/>}>
<Posts/>
</Suspense>
</ProfileLayout>
);
}
```
If an error happens in the `Posts` component or somewhere inside it, React will [try to recover from it:](/apis/react/Suspense#providing-a-fallback-for-server-errors-and-server-only-content)
1. It will emit the loading fallback for the closest `<Suspense>` boundary (`PostsGlimmer`) into the HTML.
2. It will "give up" on trying to render the `Posts` content on the server anymore.
3. When the JavaScript code loads on the client, React will *retry* rendering the `Posts` component on the client.
If retrying rendering `Posts` on the client *also* fails, React will throw the error on the client. As with all the errors thrown during rendering, the [closest parent error boundary](/apis/react/Component#static-getderivedstatefromerror) determines how to present the error to the user. In practice, this means that the user will see a loading indicator until it is certain that the error is not recoverable.
If retrying rendering `Posts` on the client succeeds, the loading fallback from the server will be replaced with the client rendering output. The user will not know that there was a server error. However, the server `onError` callback and the client [`onRecoverableError`](/apis/react-dom/client/hydrateRoot#hydrateroot) callbacks will fire so that you can get notified about the error.
---
### Setting the status code {/*setting-the-status-code*/}
Streaming introduces a tradeoff. You want to start streaming the page as early as possible so that the user can see the content sooner. However, once you start streaming, you can no longer set the response status code.
By [dividing your app](#specifying-what-goes-into-the-shell) into the shell (above all `<Suspense>` boundaries) and the rest of the content, you've already solved a part of this problem. If the shell errors, you'll get the `onShellError` callback which lets you set the error status code. Otherwise, you know that the app may recover on the client, so the "OK" status code is reasonable.
```js {4}
const { pipe } = renderToPipeableStream(<App/>, {
bootstrapScripts: ['/main.js'],
onShellReady() {
response.statusCode = 200;
pipe(response);
},
onShellError(error) {
response.statusCode = 500;
response.send('<h1>Something went wrong</h1>');
},
onError(error) {
console.error(error);
logServerCrashReport(error);
}
});
```
If a component *outside* the shell (i.e. inside a `<Suspense>` boundary) throws an error, React will not stop rendering. This means that the `onError` callback will fire, but you will still get `onShellReady` instead of `onShellError`. This is because React will try to recover from that error on the client, [as described above.](#recovering-from-errors-outside-the-shell)
However, if you'd like, you can use the fact that something has errored to set the status code:
```js {1,6,14}
let didError = false;
const { pipe } = renderToPipeableStream(<App/>, {
bootstrapScripts: ['/main.js'],
onShellReady() {
response.statusCode = didError ? 500 : 200;
pipe(response);
},
onShellError(error) {
response.statusCode = 500;
response.send('<h1>Something went wrong</h1>');
},
onError(error) {
didError = true;
console.error(error);
logServerCrashReport(error);
}
});
```
This will only catch errors outside the shell that happened while generating the initial shell content, so it's not exhaustive. If knowing whether an error occurred for some content is critical, you can move it up into the shell.
---
### Handling different errors in different ways {/*handling-different-errors-in-different-ways*/}
You can [create your own `Error` subclasses](https://javascript.info/custom-errors) and use the [`instanceof`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) operator to check which error is thrown. For example, you can define a custom `NotFoundError` and throw it from your component. Then your `onError`, `onShellReady`, and `onShellError` callbacks can do something different depending on the error type:
```js {2,4-14,19,23,28}
let didError = false;
let caughtError = null;
function getStatusCode() {
if (didError) {
if (caughtError instanceof NotFoundError) {
return 404;
} else {
return 500;
}
} else {
return 200;
}
}
const { pipe } = renderToPipeableStream(<App/>, {
bootstrapScripts: ['/main.js'],
onShellReady() {
response.statusCode = getStatusCode();
pipe(response);
},
onShellError(error) {
response.statusCode = getStatusCode();
response.send('<h1>Something went wrong</h1>');
},
onError(error) {
didError = true;
caughtError = error;
console.error(error);
logServerCrashReport(error);
}
});
```
Keep in mind that once you emit the shell and start streaming, you can't change the status code.
---
### Waiting for all content to load for crawlers and static generation {/*waiting-for-all-content-to-load-for-crawlers-and-static-generation*/}
Streaming offers a better user experience because the user can see the content as it becomes available.
However, when a crawler visits your page, or if you're generating the pages at the build time, you might want to let all of the content load first and then produce the final HTML output instead of revealing it progressively.
You can wait for all the content to load using the `onAllReady` callback:
```js {2,7,10,16-21}
let didError = false;
let isCrawler = // ... depends on your bot detection strategy ...
const { pipe } = renderToPipeableStream(<App/>, {
bootstrapScripts: ['/main.js'],
onShellReady() {
if (!isCrawler) {
response.statusCode = didError ? 500 : 200;
pipe(response);
}
},
onShellError(error) {
response.statusCode = 500;
response.send('<h1>Something went wrong</h1>');
},
onAllReady() {
if (isCrawler) {
response.statusCode = didError ? 500 : 200;
pipe(response);
}
},
onError(error) {
didError = true;
console.error(error);
logServerCrashReport(error);
}
});
```
A regular visitor will get a stream of progressively loaded content. A crawler will receive the final HTML output after all the data loads. However, this also means that the crawler will have to wait for *all* data, some of which might be slow to load or error. Depending on your app, you could choose to send the shell to the crawlers too.
---
### Aborting server rendering {/*aborting-server-rendering*/}
You can force the server rendering to "give up" after a timeout:
Call `renderToPipeableStream` to render your React tree as HTML into a [Node.js Stream.](https://nodejs.org/api/stream.html#writable-streams)
```js
import { renderToPipeableStream } from 'react-dom/server';
const { pipe } = renderToPipeableStream(<App/>, {
bootstrapScripts: ['/main.js'],
onShellReady() {
pipe(response);
}
});
```
On the client, call [`hydrateRoot`](/apis/react-dom/client/hydrateRoot) to make the server-generated HTML interactive.
#### Parameters {/*parameters*/}
* `reactNode`: A React node you want to render to HTML. For example, a JSX element like `<App />`. It is expected to represent the entire document, so the `App` component should render the `<html>` tag.
* **optional**`options`: An object with streaming 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`.](/apis/react-dom/client/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">`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) instead.
* **optional** `identifierPrefix`: A string prefix React uses for IDs generated by [`useId`.](/apis/react/useId) Useful to avoid conflicts when using multiple roots on the same page. Must be the same prefix as passed to [`hydrateRoot`.](/apis/react-dom/client/hydrateRoot#parameters)
* **optional** `namespaceURI`: A string with the root [namespace URI](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS#important_namespace_uris) 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** `nonce`: A [`nonce`](http://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#nonce) string to allow scripts for [`script-src` Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src).
* **optional** `onAllReady`: A callback that fires when all rendering is complete, including both the [shell](#specifying-what-goes-into-the-shell) and all additional [content.](#streaming-more-content-as-it-loads) You can use this instead of `onStreamReady` [for crawlers and static generation.](#waiting-for-all-content-to-load-for-crawlers-and-static-generation) If you start streaming here, you won't get any progressive loading. The stream will contain the final HTML.
* **optional** `onError`: A callback that fires whenever there is a server error, whether [recoverable](#recovering-from-errors-outside-the-shell) or [not.](#recovering-from-errors-inside-the-shell) By default, this only calls `console.error`. If you override it to [log crash reports,](#logging-crashes-on-the-server) make sure that you still call `console.error`. You can also use it to [adjust the status code](#setting-the-status-code) before the shell is emitted.
* **optional** `onShellReady`: A callback that fires right after the [initial shell](#specifying-what-goes-into-the-shell) has been rendered. You can [set the status code](#setting-the-status-code) and call `pipe` here to start streaming. React will [stream the additional content](#streaming-more-content-as-it-loads) after the shell along with the inline `<script>` tags that place that replace the HTML loading fallbacks with the content.
* **optional** `onShellError`: A callback that fires if there was an error rendering the initial shell. It receives the error as an argument. No bytes were emitted from the stream yet, and neither `onShellReady` nor `onAllReady` will get called, so you can [output a fallback HTML shell.](#recovering-from-errors-inside-the-shell)
* **optional** `progressiveChunkSize`: The number of bytes in a chunk. [Read more about the default heuristic.](https://github.com/facebook/react/blob/14c2be8dac2d5482fda8a0906a31d239df8551fc/packages/react-server/src/ReactFizzServer.js#L210-L225)
#### Returns {/*returns*/}
`renderToPipeableStream` returns an object with two methods:
* `pipe` outputs the HTML into the provided [Writable Node.js Stream.](https://nodejs.org/api/stream.html#writable-streams) Call `pipe` in `onShellReady` if you want to enable streaming, or in `onAllReady` for crawlers and static generation.
* `abort` lets you [abort server rendering](#aborting-server-rendering) and render the rest on the client.
### Rendering a React tree as static HTML to a Node.js Readable stream {/*rendering-a-react-tree-as-static-html-to-a-nodejs-readable-stream*/}
### Rendering a React tree as static HTML to a Node.js Readable Stream {/*rendering-a-react-tree-as-static-html-to-a-nodejs-readable-stream*/}
Call `renderToStaticNodeStream` to get a [Node.js Readable stream](https://nodejs.org/api/stream.html#readable-streams) which you can pipe to your server response:
Call `renderToStaticNodeStream` to get a [Node.js Readable Stream](https://nodejs.org/api/stream.html#readable-streams) which you can pipe to your server response:
```js {5-6}
import { renderToStaticNodeStream } from 'react-dom/server';
```js {3-4}
// The route handler syntax depends on your backend framework
// The route handler syntax depends on your backend framework
app.use('/', (request, response) => {
app.use('/', (request, response) => {
const stream = renderToStaticNodeStream(<Page/>);
const stream = renderToStaticNodeStream(<Page/>);
@ -46,7 +48,7 @@ Interactive apps should use [`renderToPipeableStream`](/apis/react-dom/server/re
On the server, call `renderToStaticNodeStream` to get a [Node.js Readable stream](https://nodejs.org/api/stream.html#readable-streams).
On the server, call `renderToStaticNodeStream` to get a [Node.js Readable Stream](https://nodejs.org/api/stream.html#readable-streams).
```js
```js
const stream = renderToStaticNodeStream(<Page/>);
const stream = renderToStaticNodeStream(<Page/>);
@ -61,7 +63,7 @@ The stream will produce non-interactive HTML output of your React components.
#### Returns {/*returns*/}
#### Returns {/*returns*/}
A [Node.js Readable stream](https://nodejs.org/api/stream.html#readable-streams) that outputs an HTML string. The resulting HTML can't be hydrated on the client.
A [Node.js Readable Stream](https://nodejs.org/api/stream.html#readable-streams) that outputs an HTML string. The resulting HTML can't be hydrated on the client.
dan
2 years ago
GitHub