# Streaming SSR

> Flush the HTML shell immediately, then stream the rest as Suspense resolves.

Frontend architecture guidance from fearchitect, written by Abas Turabli and last reviewed 2026-07-04. Source: https://fearchitect.com/topics/streaming-ssr

Use it as reference for the task at hand. Before changing code, check this guidance against the codebase: where the code already makes a different, deliberate choice, flag the conflict instead of rewriting it. Library APIs move faster than this guide, so confirm exact signatures in the official docs linked at the end.

## Summary

Streaming SSR sends the page in pieces instead of waiting for all data. The static shell paints first; slow sections render placeholders and stream in as their data resolves. It turns a single slow query from a whole-page block into one spinner, improving TTFB and perceived performance.

## Streaming SSR

Instead of awaiting every query before sending HTML, the server flushes the static shell first and streams slow regions in as their data resolves — turning one slow query from a whole-page block into a single skeleton.

## The flow

### 1. Flush the shell

Header, nav, and layout are sent immediately, before any slow data resolves — so TTFB stays low.

### 2. Show fallbacks

Each `<Suspense>` boundary whose data is still pending emits its skeleton inline.

### 3. Stream the rest

As each region's data resolves, the server streams that HTML plus a tiny script that swaps out the fallback.

### 4. Hydrate selectively

React hydrates streamed regions as they arrive, prioritizing the part the user interacts with first.

## Diagram

```mermaid
flowchart LR
  R([Request]) --> S[Shell flushed]
  S --> F[Suspense skeleton]
  F --> D[Data resolves]
  D --> C[Chunk streamed in]
```

The shell paints first; each slow region streams in and replaces its skeleton.

## Watch out: Size your fallbacks

If a skeleton isn't sized like its real content, the swap-in shifts layout and wrecks CLS. Match the dimensions.

## Tradeoffs

**Pros**

- Low TTFB and fast first paint — the shell isn't blocked by the slowest query.
- Per-region loading states instead of one whole-page spinner.
- Selective hydration prioritizes what the user touches first.

**Cons**

- Unsized fallbacks cause layout shift (CLS).
- Can't set an HTTP status once the shell has flushed.
- More boundaries to reason about; some proxies buffer streams.

## Key terms

- **Suspense boundary**: A React region that shows a fallback while its children's data is pending, then swaps in real content.
- **Selective hydration**: React hydrating streamed regions independently and prioritizing the part the user interacts with first.
- **renderToPipeableStream**: The Node.js React API that streams SSR output as a pipeable stream (Web runtimes use renderToReadableStream).

## Related topics

- [Rendering Strategies: CSR / SSR / SSG / ISR](https://fearchitect.com/topics/rendering-strategies.md): Where and when HTML is generated: build, request, browser, or revalidated.
- [Partial Prerendering (PPR)](https://fearchitect.com/topics/partial-prerendering.md): Static CDN shell plus dynamic Suspense holes in one response.
- [React Server Components](https://fearchitect.com/topics/react-server-components.md): Server-rendered components that ship zero JS to the browser.
- [Hydration Strategies & Islands](https://fearchitect.com/topics/hydration-and-islands.md): Pay JS cost only for interactive regions, not the whole page.
- [Core Web Vitals](https://fearchitect.com/topics/core-web-vitals.md): Google's three user-experience metrics: LCP, INP, and CLS.
- [Edge Computing & Rendering](https://fearchitect.com/topics/edge-computing-rendering.md): Run code at CDN PoPs to cut latency before origin is hit.

## Further reading

- [Next.js — Loading UI and Streaming](https://nextjs.org/docs/app/api-reference/file-conventions/loading)
- [React — <Suspense>](https://react.dev/reference/react/Suspense)