Implementing Streaming SSR with React Suspense Boundaries

Limitations of Monolithic SSR and the Shift to Streaming

For years, server-side rendering (SSR) was constrained by a critical, binary limitation: it was an all-or-nothing operation. Before a single byte of HTML could be sent to the browser, the server had to resolve all data requirements and render the entire application component tree. Similarly, once the client received the HTML, the browser had to download the entire JavaScript bundle and hydrate the complete document before the user could interact with any interactive element.

Under high-concurrency conditions or on slow networks, this architecture created severe bottlenecks, inflating Time to First Byte (TTFB) and Largest Contentful Paint (LCP) metrics. To address this, React introduced streaming server-side rendering powered by Suspense boundaries. This architectural paradigm shift allows the server to render and stream HTML progressively over a single HTTP connection, bypassing traditional data fetching and bundle delivery limitations.

At the heart of streaming SSR is the concept of incremental rendering. When a request hits the server, React begins traversing the component tree. When it encounters a Suspense boundary wrapping an asynchronous component (such as a database query or a slow API fetch), React does not block execution.

Instead, it immediately emits a placeholder—usually a fallback loading spinner—and continues rendering the rest of the application. The surrounding shell is packaged and sent to the client instantly. Once the asynchronous data resolves, React renders the actual component on the server, generates the corresponding HTML chunk, and pushes it down the same HTTP stream.

The browser receives this late-arriving chunk alongside a tiny inline script that performs a precise, zero-dependency DOM swap, replacing the fallback placeholder with the fully rendered markup.

Core Advantages of Streaming SSR

Compared to traditional SSR, Streaming SSR with Suspense boundaries offers several key advantages:

• Reduced Time to First Byte (TTFB): The server can immediately send the HTML shell of the page without waiting for slow database queries to resolve.
• Improved Largest Contentful Paint (LCP): Critical layout components and media elements are rendered and hydrated early, improving perceived load speeds.
• Selective Hydration: React prioritizes interactive components that the user interacts with first, rather than forcing a blocking, page-wide hydration cycle.
• Robust Error Isolation: Failures in specific dynamic modules are caught by localized Error Boundaries, allowing the rest of the application to render normally.

HTML Chunks and Dynamic DOM Insertion

Let's look at the underlying mechanics of this progressive rendering stream. On V8 engine-based edge networks or serverless runtimes, React exposes the renderToReadableStream API. API. This returns a Web Streams API ReadableStream, which can be piped directly into the HTTP response. The stream contains line-delimited HTML chunks interleaved with React’s internal control commands.

For example, when a Suspense boundary with ID B:1 is suspended, React outputs:

<!--$?--><template id="B:1"></template>...fallback markup...<!--/$-->

The comment tags <!--$?--> and <!--/$--> act as markers for React's client-side runtime. When the backend resolves the promise, it streams the final markup wrapped in a hidden container, followed by an execution script:

Selective Hydration and User-Interaction Prioritization

<div hidden id="S:1">
  <p>This is the resolved dynamic content rendered on the server!</p>
</div>
<script>
  $RC('B:1', 'S:1');
</script>

Data-Fetching Patterns and Infrastructure Configuration

The $RC function (React Client Runtime function) is a highly optimized helper that selects the template with ID B:1, removes the fallback elements, and inserts the children of the hidden S:1 container in their place. Because this occurs directly as the browser receives the stream, the visual transition is immediate and does not require the main JavaScript bundles to finish downloading or executing.

Hydration is the final, computationally expensive phase where static HTML is transformed into an interactive application. In traditional architectures, hydration is monolithic: the browser must parse and run the entire JavaScript bundle to attach event listeners to every node on the page. Under React's streaming architecture, hydration becomes selective.

React can hydrate components as soon as their code and data become available, even while other parts of the page are still streaming or suspended. If the user clicks on a suspended component before it has been hydrated, React prioritizes the hydration of that specific branch. This dynamic prioritization is called Selective Hydration, and it ensures that user input is processed with minimal delay, drastically reducing Total Blocking Time (TBT).

React Streaming SSR Optimization at the Edge with Bramsley

Designing applications for streaming SSR requires careful orchestration of the data-fetching layer. Developers must leverage modern React features such as the use hook to resolve promises directly in the render phase. When a promise is passed to use(promise), it alerts the nearest parent Suspense boundary, telling it to yield execution and render the fallback.

Managing these promises without creating memory leaks or redundant requests requires a robust caching layout. Below is an example of an edge-compatible streaming component that uses Suspense to stream data-heavy components: