Streaming with Suspense

## Two halves of a streamed response A streamed server render produces one HTTP response made of many chunks, and it is useful to think of it as two categories. **The shell** is everything that is *not* inside a currently pending `<Suspense>` boundary. React renders it eagerly. Wherever it meets a boundary whose children have suspended, it does not stop — it renders that boundary's `fallback` into the output at that exact position and moves on. Once the shell is complete, React flushes it. This first flush is the whole point of streaming: it contains `<head>`, the CSS and script tags, the layout, and all the content that had its data ready, so the browser can start fetching subresources and painting. **The late chunks** carry the subtrees that were still pending. They are written to the same open response as they resolve. A consequence worth internalising: if anything *outside* every boundary suspends, there is no shell yet, so nothing is flushed at all. The shell is the unit of "first byte", and it is gated by the slowest thing you left unwrapped. ## How a late chunk gets into the right place HTML arriving later is appended at the end of the document — that is how a parser works, and it is nowhere near the hole the fallback is sitting in. React solves this with a hidden container plus a small inline script. The chunk looks structurally like this: ```html <div hidden id="S:0"><ul>…the real recommendations…</ul></div> <script>/* React's inline runtime: replace boundary B:0 with S:0 */</script> ``` The boundary's position in the shell was marked when it was flushed, so the script knows where to put things. It moves the nodes out of the hidden container into that slot, removes the fallback nodes, and updates the boundary's markers. Three properties fall out of this design: 1. **No application JavaScript is needed.** The script is a few lines inlined into the HTML by React, so the swap happens as the browser parses that chunk — potentially long before your bundle has downloaded, and independent of hydration. 2. **The swap is incremental and local.** Only that boundary's DOM changes; the rest of the already-painted page is untouched, so there is no re-render or flash of the whole document. 3. **Order is completion order.** React writes a boundary's chunk when its data resolves, not when its position in the document says it should. Three sibling boundaries can therefore appear third, first, second. ## Nesting Boundaries can be nested, and a nested boundary cannot be revealed before the boundary that contains it — its slot does not exist in the live DOM while the outer fallback is showing. React handles this by holding the inner content until the outer boundary is swapped in, at which point the inner one follows. That is the only ordering guarantee streaming gives you; siblings have none. ## Errors after the first flush Once the shell is out, the status code and headers are committed. A failure inside a still-pending boundary therefore cannot become a 500 or a redirect. What React does instead is stream an instruction to the client so the boundary switches to client rendering: the browser keeps the fallback and, after hydration, retries rendering that subtree on the client, where an error boundary can catch it. This is why teams distinguish "failed before the shell" (still a real HTTP error) from "failed after the shell" (a client-side recovery path) when they design error handling for streamed pages. ## What this means in practice - **A boundary is a flush point.** More boundaries means more, smaller chunks and earlier first paint for the shell; zero boundaries means classic buffered SSR. - **The fallback is real server HTML**, present in the first bytes, so a skeleton shows even with JavaScript disabled — but the late content will never appear for such a client, because the swap script cannot run. - **Intermediaries matter.** A proxy, CDN or compression layer that buffers the response defeats the mechanism: the user gets everything at the end. This is a routine cause of "streaming does nothing in production but works locally". - **Don't confuse the swap with hydration.** Getting the markup on screen is the inline script's job. Attaching React to that markup and making it interactive is a separate, later step. ## Common wrong answers Candidates often say the browser "re-renders the page" when a chunk arrives, or that React opens a second request per boundary, or that the late content is delivered over a WebSocket. It is one response, appended to, with an inline script doing a DOM move. Others assume the chunks must arrive in document order — they do not, and that out-of-order behaviour is the reason streaming is worth doing at all.