React 18 Streaming: How renderToPipeableStream Works

Before React 18, server-side rendering used renderToString, which is synchronous: React renders the entire component tree to a string before sending any HTML to the browser. If any component loads data, the server must wait for all data before the first byte reaches the user.

React 18 introduced renderToPipeableStream, which renders the component tree as a stream of HTML chunks. Instead of waiting for everything to be ready, React sends HTML as it completes each part of the tree, allowing the browser to start rendering visible content immediately.

renderToPipeableStream returns an object with two methods: pipe(writable) and abort(). pipe accepts a Node.js Writable stream (typically the HTTP response) and starts streaming HTML to it. abort() cancels the stream, used when the request is cancelled or a timeout is exceeded.

The stream begins with the HTML shell — all the content that is not blocked by a pending Suspense boundary. This includes the document head, navigation, footer, layout chrome, and any synchronously-available content. The shell streams immediately, before any data-dependent components resolve.

Components inside Suspense boundaries that are waiting for data initially stream as their fallback UI (e.g., a loading spinner). React sends a script tag later that replaces the fallback with the resolved content — all without a client-side re-render of the shell.

Pass bootstrapScripts: ['/static/js/client.js'] to renderToPipeableStream to tell React to inject a script tag at the end of the stream. The browser loads this bundle and calls hydrateRoot, attaching React's event handlers to the server-rendered DOM.

onShellReady fires when the HTML shell (everything outside pending Suspense boundaries) is ready to send. This is the correct moment to call pipe(res) — but importantly, set the HTTP status code and response headers before calling pipe, since streaming locks in the HTTP status.

Because streaming begins immediately when you call pipe(), any res.setHeader or res.statusCode assignments must happen before the pipe call. A common pattern is to set status 200 and Content-Type: text/html in the onShellReady callback, then call pipe(res) immediately after.

onShellError fires when an unrecoverable error occurs before the shell finishes rendering — for example, a top-level component throws outside of any Suspense boundary. In this case, you cannot stream a partial response; instead, redirect to an error page or send a static error HTML document.

onAllReady fires when the entire React tree has resolved — including all Suspense boundaries. For search engine crawlers and social media link previewers, you want to send the complete HTML without streaming. Check if the request is from a bot and call pipe(res) in onAllReady instead of onShellReady.

onError fires for errors in Suspense boundaries — React can still stream the rest of the page while that boundary falls back to its error UI. Use onError to log the error to your observability pipeline without aborting the stream for the user.

When should you use onAllReady instead of onShellReady to start piping?

renderToPipeableStream is React 18's streaming SSR primitive for Node.js servers. It streams the HTML shell immediately via onShellReady, fills in Suspense boundaries as data resolves, and hydrates the client via bootstrapScripts. Use onAllReady for bots and crawlers, onShellError for fatal failures, and always set HTTP headers before calling pipe().