[18] renderToPipeableStream doc (#4485)

salazarm · web-flow · commit c0ef494397d4 · 2022-03-28T16:14:54.000-04:00
* new streaming ssr api

* add readable stream

* code snippets
diff --git a/content/docs/reference-react-dom-server.md b/content/docs/reference-react-dom-server.md
@@ -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)
 
 * * *
@@ -55,7 +57,84 @@ If you plan to use React on the client to make the markup interactive, do not us
 
 * * *
 
-### `renderToNodeStream()` {#rendertonodestream}
+### `renderToPipeableStream()` {#rendertopipeablestream}
+
+```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)
+
+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:
+>
+> This is a Node.js specific API and modern server environments should use renderToReadableStream instead.
+>
+
+```
+const {pipe, abort} = renderToPipeableStream(
+  <App />,
+  {
+    onAllReady() {
+      res.statusCode = 200;
+      res.setHeader('Content-type', 'text/html');
+      pipe(res);
+    },
+    onShellError(x) {
+      res.statusCode = 500;
+      res.send(
+        '<!doctype html><p>Loading...</p><script src="clientrender.js"></script>'
+      );
+    }
+  }
+);
+```
+
+* * *
+
+### `renderToReadableStream()` {#rendertoreadablestream}
+
+```javascript
+    ReactDOMServer.renderToReadableStream(element, options);
+```
+
+Streams a React element to its initial HTML. Returns a [Readable Stream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream). Fully supports Suspense and streaming of HTML. [Read more](https://github.com/reactwg/react-18/discussions/127)
+
+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.
+
+```
+let controller = new AbortController();
+try {
+  let stream = await renderToReadableStream(
+    <html>
+      <body>Success</body>
+    </html>,
+    {
+      signal: controller.signal,
+    }
+  );
+  
+  // This is to wait for all suspense boundaries to be ready. You can uncomment
+  // this line if you don't want to stream to the client
+  // await stream.allReady;
+
+  return new Response(stream, {
+    headers: {'Content-Type': 'text/html'},
+  });
+} catch (error) {
+  return new Response(
+    '<!doctype html><p>Loading...</p><script src="clientrender.js"></script>',
+    {
+      status: 500,
+      headers: {'Content-Type': 'text/html'},
+    }
+  );
+}
+```
+* * *
+
+### `renderToNodeStream()` {#rendertonodestream} (Deprecated)
 
 ```javascript
 ReactDOMServer.renderToNodeStream(element)
