Skip to content

[18] renderToPipeableStream doc #4485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
salazarm merged 3 commits into from
Mar 28, 2022
Merged

[18] renderToPipeableStream doc #4485

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ee94c1e
new streaming ssr api
salazarm Mar 23, 2022
ea4c6eb
add readable stream
salazarm Mar 25, 2022
2d802b5
code snippets
salazarm Mar 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 37 additions & 2 deletions content/docs/reference-react-dom-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@ The following methods can be used in both the server and browser environments:

These additional methods depend on a package (`stream`) that is **only available on the server**, and won't work in the browser.

- [`renderToNodeStream()`](#rendertonodestream)
- [`renderToPipeableStream()`](#rendertopipeablestream)
- [`renderToReadableStream()`](#rendertoreadablestream)
- [`renderToNodeStream()`](#rendertonodestream) (Deprecated)
- [`renderToStaticNodeStream()`](#rendertostaticnodestream)

* * *
Expand Down Expand Up @@ -54,8 +56,41 @@ Similar to [`renderToString`](#rendertostring), except this doesn't create extra
If you plan to use React on the client to make the markup interactive, do not use this method. Instead, use [`renderToString`](#rendertostring) on the server and [`ReactDOM.hydrateRoot()`](/docs/react-dom-client.html#hydrateroot) on the client.

* * *
### `renderToPipeableStream()` {#rendertopipeablestream}

### `renderToNodeStream()` {#rendertonodestream}
```javascript
ReactDOMServer.renderToPipeableStream(element, options)
```

Render a React element to its initial HTML. Returns a [Control object](https://github.com/facebook/react/blob/3f8990898309c61c817fbf663f5221d9a00d0eaa/packages/react-dom/src/server/ReactDOMFizzServerNode.js#L49-L54) that allows you to pipe the output or abort the request. Fully supports Suspense and streaming of HTML with "delayed" content blocks "popping in" later through javascript execution. [Read more](https://github.com/reactwg/react-18/discussions/37)
Copy link
Copy Markdown
Contributor

@sebmarkbage sebmarkbage Mar 26, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should rename that Control type. I think of it as a PipeableStream object. It's kind of like Node's "ReadableStream" except limited to the pipe function and with the addition of the abort().


If you call [`ReactDOM.hydrateRoot()`](/docs/react-dom-client.html#hydrateroot) on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience.

> Note:
>
> Server-only. This API is not available in the browser.
Copy link
Copy Markdown
Contributor

@sebmarkbage sebmarkbage Mar 26, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's worth highlighting that this is a Node.js specific API and that "modern server environments should use renderToReadableStream instead".

Copy link
Copy Markdown
Member

@gaearon gaearon Mar 28, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wait.. do we not consider Node.js modern anymore? 😄 I'd understand "edge server environments" but "modern" sounds harsh.

>

* * *

### `renderToReadableStream()` {#rendertoreadablestream}

```javascript
ReactDOMServer.renderToReadableStream(element, options);
```

Render a React element to its initial HTML. Returns a [Readable Stream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream). Fully supports Suspense but not streaming of HTML. [Read more](https://github.com/reactwg/react-18/discussions/127)
Copy link
Copy Markdown
Contributor

@sebmarkbage sebmarkbage Mar 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the API that canonical for streaming HTML. The one that doesn't stream HTML is renderToNodeStream.


If you call [`ReactDOM.hydrateRoot()`](/docs/react-dom-client.html#hydrateroot) on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience.

> Note:
>
> Server-only. This API is not available in the browser.
Copy link
Copy Markdown
Contributor

@sebmarkbage sebmarkbage Mar 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This actually not server-only. https://github.com/facebook/react/blob/main/packages/react-dom/server.browser.js#L40

It's more intended for Service Workers specifically though.

>

* * *

### `renderToNodeStream()` {#rendertonodestream} (Deprecated)

```javascript
ReactDOMServer.renderToNodeStream(element)
Expand Down