Streaming Server-Side Rendering
We can reduce the Time To Interactive while still server rendering our application by streaming the contents of our application. Instead of generating one large HTML string containing the necessary markup for the current navigation, we can send the shell first and stream slower parts later. The moment the client receives the first chunks of HTML, it can start parsing and painting the page.
Modern React streaming uses renderToPipeableStream() on Node runtimes or renderToReadableStream() on Web Stream runtimes, then hydrates the response with hydrateRoot() on the client.
When to Use
- Use this when you want to improve TTFB and FCP by sending HTML incrementally as it's generated
- This is helpful for large pages where waiting for the full HTML would delay the initial paint
When NOT to Use
- When your hosting environment doesn't support streaming responses (some serverless platforms buffer the full response)
- For simple static pages where the HTML is small enough that streaming provides no meaningful improvement
- When middleware or reverse proxies in your stack buffer the response, negating the streaming benefit
Instructions
- Use
renderToPipeableStream(React 18+) instead of the deprecatedrenderToNodeStream - Combine streaming with
Suspenseboundaries to stream partial content while slow parts load - Use the
onShellReadycallback to begin streaming once the critical shell is ready - Handle streaming errors with the
onErrorcallback
Details
The initial HTML gets sent to the response object alongside the chunks of data from the App component:
html<!DOCTYPE html> <html> <head> <title>Cat Facts</title> <link rel="stylesheet" href="/style.css" /> <script type="module" defer src="/build/client.js"></script> </head> <body> <h1>Stream Rendered Cat Facts!</h1> <div id="approot"></div> </body> </html>
Modern React streaming on Node uses renderToPipeableStream:
jsimport { renderToPipeableStream } from "react-dom/server"; app.use("*", (request, response) => { let didError = false; const { pipe } = renderToPipeableStream(<App />, { bootstrapScripts: ["/build/client.js"], onShellReady() { response.statusCode = didError ? 500 : 200; response.setHeader("Content-Type", "text/html"); pipe(response); }, onError(error) { didError = true; console.error(error); }, }); });
If we were to server render the App component using renderToString, we would have to wait until the entire tree had rendered before sending the response. With streaming, the server can flush the shell early and continue sending slower content as it becomes ready.
Concepts
Like progressive hydration, streaming is another rendering mechanism that can be used to improve SSR performance. As the name suggests, streaming implies chunks of HTML are streamed from the node server to the client as they are generated. As the client starts receiving "bytes" of HTML earlier even for large pages, the TTFB is reduced and relatively constant. All major browsers start parsing and rendering streamed content or the partial response earlier. As the rendering is progressive, it results in a fast FP and FCP.
Streaming responds well to network backpressure. If the network is clogged and not able to transfer any more bytes, the renderer gets a signal and stops streaming till the network is cleared up. Thus, the server uses less memory and is more responsive to I/O conditions. This enables your Node.js server to render multiple requests at the same time and prevents heavier requests from blocking lighter requests for a long time. As a result, the site stays responsive even in challenging conditions.
React for Streaming
React 18 introduced the modern streaming APIs:
renderToPipeableStream(element, options)for Node.js HTTP responses.renderToReadableStream(element, options)for Web Streams runtimes such as edge environments.
These APIs support Suspense boundaries, onShellReady, onAllReady, and progressive hydration through hydrateRoot() on the client.
The stream output can emit bytes as soon as the shell is ready. The response progressively sends chunks of data to the client while slower chunks continue rendering on the server.
Streaming SSR - Pros and Cons
Streaming aims to improve the speed of SSR with React and provides the following benefits:
-
Performance Improvement: As the first byte reaches the client soon after rendering starts on the server, the TTFB is better than that for SSR. It is also more consistent irrespective of the page size. Since the client can start parsing HTML as soon as it receives it, the FP and FCP are also lower.
-
Handling of Backpressure: Streaming responds well to network backpressure or congestion and can result in responsive websites even under challenging conditions.
-
Supports SEO: The streamed response can be read by search engine crawlers, thus allowing for SEO on the website.
It is important to note that streaming implementation is not a simple find-replace from renderToString to renderToPipeableStream(). There are cases where the code that works with SSR may not work as-is with streaming:
-
Frameworks that use the server-render-pass to generate markup that needs to be added to the document before the SSR-ed chunk. Examples are frameworks that dynamically determine which CSS to add to the page in a preceding
<style>tag. -
Code, where
renderToStaticMarkupis used to generate the page template andrenderToStringcalls are embedded to generate dynamic content. Since the string corresponding to the component is expected in these cases, it cannot be replaced by a stream. For example:
jsres.write("<!DOCTYPE html>"); res.write(renderToStaticMarkup( <html> <head> <title>My Page</title> </head> <body> <div id="content"> { renderToString(<MyPage/>) } </div> </body> </html>);
Both Streaming and Progressive Hydration can help to bridge the gap between a pure SSR and a CSR experience.
