ReactPerformance

Streaming pages with Server Components

Send the shell first and fill in slow parts as they resolve. A walk through Suspense boundaries, loading states and what the user actually sees.

Alex Rivera

· 7 min read

A stream falling over layered rock in a green gorge

The problem with waiting

A traditional server-rendered page is only as fast as its slowest query. If the product details take 40 ms but the recommendations take 900 ms, the user stares at a blank tab for almost a second, even though most of the page was ready almost immediately.

Streaming flips that around. The server sends HTML as soon as it has any, and keeps the connection open to send the rest. The browser paints the header, the navigation and the main content right away, and the slow parts slot in when they are done.

Suspense boundaries

In React, the unit of streaming is a <Suspense> boundary. Everything outside it is part of the first chunk; everything inside it can arrive later, with the fallback shown in the meantime.

tsx
import { Suspense } from "react";export default async function ProductPage({ params }: PageProps<"/p/[id]">) {  const { id } = await params;  const product = await getProduct(id); // fast  return (    <>      <ProductDetails product={product} />      <Suspense fallback={<RecommendationsSkeleton />}>        <Recommendations productId={id} /> {/* slow */}      </Suspense>    </>  );}

Where you put the boundary is a design decision, not just a technical one. Too many boundaries and the page pops in piece by piece; too few and you're back to waiting on the slowest part.

Designing fallbacks

A good fallback has the same size as the content it stands in for, so nothing jumps when the real content arrives. It should be quiet: a few muted blocks, not a spinner in the middle of the page.

  • Match the final layout's height to avoid layout shift.
  • Keep the number of distinct loading states small.
  • Announce loading once to screen readers, not once per block.

Measuring the result

The metric that moves the most is time to first byte, followed by first contentful paint. Total load time often stays the same, because the slow query is still slow. That's fine: what users notice is how long they wait before something useful appears.

bash
# Watch chunks arrive one by onecurl -N --no-buffer https://localhost:3000/p/42

Keep reading