Implementing Streaming SSR for a web application
Classic SSR blocks: server waits for all data, renders full HTML, sends it. Until the slowest database request finishes — browser receives nothing. Streaming SSR breaks this block: HTML is sent to browser as parts become ready, via HTTP chunked transfer encoding.
Browser starts parsing and displaying HTML immediately. Slow parts appear later. User sees something on screen in 100–200ms even if full render takes a second.
Mechanics of Streaming SSR
HTTP/1.1 supports Transfer-Encoding: chunked — server sends data in parts without Content-Length header. React and Vue use this for streaming:
Client receives:
[Chunk 1 — 50ms] <html><head>...</head><body><header>...</header>
[Chunk 2 — 120ms] <main><nav>...</nav><div id="products-suspense"><!--$?--><template id="B:0">...skeleton...</template>
[Chunk 3 — 340ms] <div hidden id="S:0"><ul><li>Product 1</li>...<!-- Data ready --></ul></div><script>$RC("B:0","S:0")</script>
[Chunk 4 — 890ms] <aside><!-- Recommendations --></aside></main></body></html>
Browser renders each chunk immediately. $RC is React script replacing skeleton with real content.
Implementation in React 18 + Next.js
// app/catalog/page.tsx
import { Suspense } from 'react';
// Intentionally slow component — simulates external API request
async function FeaturedProducts() {
// Slow external service — 800ms
const products = await fetch('https://api.example.com/featured', {
next: { revalidate: 300 }
}).then(r => r.json());
return (
<ul>
{products.map((p: Product) => (
<li key={p.id}>{p.name}</li>
))}
</ul>
);
}
async function Categories() {
// Fast internal request — 50ms
const cats = await db.category.findMany();
return <nav>{cats.map(c => <a key={c.id} href={`/catalog/${c.slug}`}>{c.name}</a>)}</nav>;
}
export default function CatalogPage() {
return (
<div>
{/* Renders immediately — synchronous */}
<h1>Catalog</h1>
{/* Fast block — appears in ~50ms */}
<Suspense fallback={<CategoriesSkeleton />}>
<Categories />
</Suspense>
{/* Slow block — appears in ~800ms, rest not blocked */}
<Suspense fallback={<ProductsGridSkeleton count={6} />}>
<FeaturedProducts />
</Suspense>
</div>
);
}
Parallel data fetching
Critical error — sequential awaits (waterfall):
// Bad: 200ms + 500ms + 300ms = 1000ms wait
async function Page() {
const user = await getUser(); // 200ms
const orders = await getOrders(user.id); // 500ms
const stats = await getStats(user.id); // 300ms
...
}
// Good: max(200ms, 500ms, 300ms) = 500ms
async function Page() {
const userPromise = getUser();
const [user, orders, stats] = await Promise.all([
userPromise,
userPromise.then(u => getOrders(u.id)),
userPromise.then(u => getStats(u.id)),
]);
...
}
Even better — split independent data across different Suspense components so they stream in parallel without single Promise.all:
export default function DashboardPage() {
// All three requests start in parallel
// Each block appears as soon as its data is ready
return (
<main>
<Suspense fallback={<UserCardSkeleton />}>
<UserCard /> {/* getUser() — 200ms */}
</Suspense>
<Suspense fallback={<OrdersSkeleton />}>
<RecentOrders /> {/* getOrders() — 500ms */}
</Suspense>
<Suspense fallback={<StatsSkeleton />}>
<DashboardStats /> {/* getStats() — 300ms */}
</Suspense>
</main>
);
}
Streaming in Node.js without framework
For custom servers — renderToPipeableStream:
import { renderToPipeableStream } from 'react-dom/server';
import { createServer } from 'http';
createServer((req, res) => {
res.setHeader('Content-Type', 'text/html; charset=utf-8');
res.setHeader('Transfer-Encoding', 'chunked');
const { pipe, abort } = renderToPipeableStream(<App url={req.url} />, {
bootstrapScripts: ['/static/js/main.js'],
onShellReady() {
// Shell ready (content before first Suspense) — start streaming
res.statusCode = 200;
pipe(res);
},
onShellError(error) {
// Shell doesn't render — fallback to CSR
res.statusCode = 500;
res.end('<html><body><div id="root"></div></body></html>');
},
onError(error) {
console.error('Streaming error:', error);
},
});
// Timeout for very slow components
setTimeout(() => abort(), 10000);
}).listen(3000);
Edge Streaming with Cloudflare Workers
// worker.ts
import { renderToReadableStream } from 'react-dom/server';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
const stream = await renderToReadableStream(
<App url={url.pathname} env={env} />,
{
bootstrapScripts: ['/main.js'],
onError: console.error,
}
);
// Wait for shell (critical path) but don't wait for Suspense
await stream.allReady; // Optional: wait for everything for bots
return new Response(stream, {
headers: {
'Content-Type': 'text/html; charset=utf-8',
'Transfer-Encoding': 'chunked',
},
});
},
};
Streaming metadata and headers
Problem with streaming: <head> is sent first, before data is ready. Metadata from async components must be passed separately:
// Next.js solves via generateMetadata — runs separate from page render
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const product = await getProduct(params.id);
return {
title: product.name,
description: product.description,
};
}
// generateMetadata and Page component run in parallel
// Streaming starts as soon as generateMetadata completes
Loading UI and skeleton strategies
app/
catalog/
loading.tsx # Automatic Suspense fallback for entire route
page.tsx
// app/catalog/loading.tsx — renders while page.tsx loads data
export default function CatalogLoading() {
return (
<div className="grid grid-cols-3 gap-4">
{Array.from({ length: 9 }).map((_, i) => (
<div key={i} className="animate-pulse bg-gray-200 rounded-lg h-64" />
))}
</div>
);
}
Metrics impact of Streaming SSR
| Metric | Without streaming | With streaming |
|---|---|---|
| TTFB | After render (500–1500ms) | Before render (< 100ms) |
| FCP | After TTFB + parsing | Right after shell |
| LCP | Depends on slow data | Depends on needed block only |
| INP | Blocked until hydration | Hydration starts earlier |
Implementation timeline
- Week 1–2: audit current SSR, identify slow requests, refactor for Suspense boundaries
- Week 3: parallelize Promise.all and independent Suspense blocks
- Week 4: skeleton UI for all Suspense fallbacks, loading.tsx for routes
- Week 5: measure Core Web Vitals before/after, optimize shell time
- Week 6: monitor streaming in production, alert on slow chunks