Network & PerformanceBaseline · Widely

Streaming SSR & Progressive Flushing

Mental Model

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.

Interactive Simulator

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.

Step 1 / 3: 1. Flush <head> + App Shell (t=15ms)

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">...');
Internal State / Memory
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.

  1. The server commits 200 OK and flushes <!doctype html><head>... plus fallback placeholders immediately, dropping TTFB to ~20 ms.
  2. The HTML parser builds the DOM incrementally without waiting for </html>, starting CSS/JS fetches and painting the shell.
  3. 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.
JS
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 and ReadableStream across Node, Deno, and Edge runtimes.

Production Pitfalls

Production Pitfall
  • 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 a 404 or 500 status code if a deep query fails, SEO crawlers will index the 200 error fallback.
When Not to Use
  • When not to use Streaming SSR: On static or edge-cached pages that render in under 15 ms, full-response caching with s-maxage is simpler and avoids open long-lived connections; if client hydration cost dominates, compare against Resumability vs Hydration.

Connections & Logical Next Steps

Seen in Architecture Autopsies

Mechanical Comparisons