Streaming SSR & Progressive Flushing
Streaming SSR stops waiting for the slowest database query before sending byte zero. The server flushes <head> and the static shell immediately (letting the browser fetch CSS and paint FCP) then streams deferred <template> chunks with tiny inline swap scripts as slow data resolves.
Streaming SSR: Shell Flush to Out-of-Order Swap
Trace how progressive HTML chunk flushing unlocks early CSS/JS fetches before slow DB queries finish.
Server commits HTTP 200 and flushes <head> with CSS/JS links plus a loading fallback placeholder.
res.write('<!doctype html><html><head><link rel="stylesheet" href="/app.css">...');- ttfbMs
- 15
- cssFetchStarted
- true
- dbQueryComplete
- false
Under the Hood
Classic buffered SSR holds the entire HTTP response hostage until the slowest microservice replies, starving both the Preload Scanner and the user's screen. Streaming SSR works like a sushi conveyor belt: plates leave the kitchen as soon as they're ready over HTTP/2 & HTTP/3.
- The server commits
200 OKand flushes<!doctype html><head>...plus fallback placeholders immediately, dropping TTFB to ~20 ms. - The HTML parser builds the DOM incrementally without waiting for
</html>, starting CSS/JS fetches and painting the shell. - When an async boundary resolves, the server appends a hidden
<template id="B:1">and a 2-line inline<script>that swaps it into the placeholder.
const stream = new ReadableStream({
async start(controller) {
controller.enqueue(encode('<!doctype html><html><head><link rel="stylesheet" href="/app.css"></head><body><div id="slot">Loading...</div>'));
const data = await fetchSlowRecommendations();
controller.enqueue(encode(`<template id="t1">${renderList(data)}</template><script>slot.replaceWith(t1.content)</script></body></html>`));
controller.close();
},
});Problem Genealogy
- 2010 (Facebook BigPipe): Pioneered out-of-order HTML chunk flushing with inline
<script>pagelet swaps, years before React existed. - 2016 (Buffered
renderToString): Forced synchronous full-tree rendering on Node.js, blocking the server event loop and delaying TTFB. - 2022+ (
renderToReadableStream& Web Streams): Combined Web Streams with Suspense boundaries andReadableStreamacross Node, Deno, and Edge runtimes.
Production Pitfalls
- Proxy buffering eating your stream: Reverse proxies (Nginx, misconfigured CDNs, or synchronous compression) often buffer the first 4–64 KB before forwarding, defeating Streams API Backpressure and turning streaming back into buffered SSR.
- Locked HTTP 200 status codes: Once the
<head>flushes, you cannot retroactively send a404or500status code if a deep query fails, SEO crawlers will index the200error fallback.
- When not to use Streaming SSR: On static or edge-cached pages that render in under 15 ms, full-response caching with
s-maxageis simpler and avoids open long-lived connections; if client hydration cost dominates, compare against Resumability vs Hydration.
Connections & Logical Next Steps
Suspense boundaries isolate hydration mismatches to a single streamed chunk instead of bailing out the entire document.
Both hydration and resumability boot on top of server-rendered HTML streamed to the browser.
Flushing <head> early lets the preload scanner fetch CSS and JS while the server awaits DB queries.
Chunked DATA frames stream progressively over a single multiplexed connection.
Streaming SSR writes HTML chunks through a ReadableStream that respects socket backpressure.
103 sends Link headers before 200 OK; Streaming SSR flushes actual 200 OK HTML bytes early.
Streaming SSR still hydrates streamed HTML on the client, whereas resumability serializes listener boundaries to skip eager hydration.
Seen in Architecture Autopsies
Mechanical Comparisons
103 sends Link headers before 200 OK; Streaming SSR flushes actual 200 OK HTML bytes early.
Streaming SSR still hydrates streamed HTML on the client, whereas resumability serializes listener boundaries to skip eager hydration.