Streaming SSR from the Edge

When a server streams HTML, the browser receives and renders content in chunks rather than waiting for the complete document. This means users see and interact with the visible parts of the page — the header, navigation, hero section — while slower data-dependent sections are still loading.

Passing bootstrapScripts to renderToReadableStream tells React where the client-side JS bundle lives. React injects a script tag at the end of the stream so the browser loads the bundle and calls hydrateRoot, making the page interactive as each section finishes streaming.

React's streaming relies on Suspense boundaries to split the component tree into independently streamable sections. Components inside a Suspense boundary that are waiting for data (via a thrown Promise) stream as placeholders first, then resolve and stream their real content later.

The onShellReady callback fires when the non-suspended HTML shell — everything outside of Suspense boundaries — is ready to stream. This is the correct moment to set the HTTP status code and response headers, then call pipe(res) or begin reading from the ReadableStream.

HTTP status codes and headers must be sent before the response body begins. Because streaming starts with onShellReady, any error handling logic (setting status 500, redirecting) must happen before the shell starts flowing — once streaming begins, the status code is locked.

onShellError fires when a fatal error occurs before the shell is ready — for example, an error in a top-level component outside any Suspense boundary. In this case, the shell never streams, and you should respond with a static error page or redirect to an error route.

onError fires for recoverable errors within Suspense boundaries. React can still stream the rest of the page; the errored boundary renders its error fallback UI. Use onError for logging: capture the error to your observability platform without aborting the stream.

If a Suspense boundary's data takes too long, stream the shell anyway and let the boundary hydrate on the client. Implement a timeout: after 5 seconds, call abort() on the stream if the boundary hasn't resolved, and the client will fetch the data itself via useEffect.

The Workers runtime passes the ReadableStream directly as the Response body. Cloudflare's infrastructure forwards each chunk to the user's browser as React produces it, without buffering the entire document. This means the first bytes of HTML leave the edge PoP within milliseconds of the request arriving.

renderToReadableStream returns an abort controller function. If the request is cancelled (user navigates away), calling abort() stops React from continuing to render and process data. This prevents wasted computation on orphaned requests and keeps Worker CPU usage bounded.

With edge streaming, the full latency chain looks like: 5ms (request to nearest PoP) + 2ms (Worker cold start) + 8ms (shell render) = 15ms to first byte. The user's browser renders the LCP element from the shell while the rest of the page continues streaming in the background.

When exactly does the onShellReady callback fire during streaming SSR?

Streaming SSR from the edge delivers HTML in chunks, improving FCP and LCP by sending the shell immediately. Suspense boundaries divide the tree into independently streamable sections. onShellReady is the signal to start piping — set status codes before calling it. onShellError handles fatal failures, onError handles recoverable ones, and abort() prevents wasted work on cancelled requests.