Streaming & Suspense: the response as a stream

Without streaming, a server builds the whole HTML document and only then sends it, so the page is as slow as its slowest query. With streaming the server sends the parts that are ready now and the rest later, in the same response, using chunked transfer encoding.

Here is that at the HTTP level, from a small node:http server that writes three pieces 800 ms apart, read with fetch and a stream reader:

/plain: status 200, transfer-encoding=chunked, content-length=null
  +  31ms  <p>shell</p>
  + 827ms  <p>slow part</p>
  +1628ms  <p>end</p>

No Content-Length (the server doesn't know it yet), and the first bytes arrive in 31 ms although the response takes 1.6 s. The browser starts painting from the first chunk.

The App Router does this for you, and <Suspense> decides where the cuts go:

// app/dashboard/page.tsx
import { Suspense } from "react";

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<p>Loading revenue…</p>}>
        <Revenue />          {/* async: ~200 ms */}
      </Suspense>
      <Suspense fallback={<p>Loading orders…</p>}>
        <RecentOrders />     {/* async: ~1 s */}
      </Suspense>
    </div>
  );
}

The first chunk carries the <h1> and both fallbacks: the static shell. When Revenue resolves, React streams its HTML plus a tiny inline script that swaps it in for the fallback. A second later the orders do the same. Each boundary resolves on its own: the slow one never holds up the fast one, and none of them holds up the shell.

That's the whole mental model:

• everything outside any pending boundary → first chunk;
• each <Suspense> boundary → its fallback first, its real content when its async work finishes;
• the user sees the page fill in section by section, and can interact with what has hydrated.

An await blocks everything rendered after it in the same component, and everything below that component. So the higher an await sits, the more of the page waits for it.

// ❌ app/products/[id]/page.tsx — one slow call holds the whole page
export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await getProduct(id);                 // 80 ms
  const recommendations = await getRecommendations(id); // 2.5 s
  return (
    <>
      <ProductDetails product={product} />
      <Recommendations items={recommendations} />
    </>
  );
}

Nothing can stream until the 2.5-second call returns, because the JSX that would contain the <Suspense> boundaries hasn't been produced yet. Move the slow await into the component that needs it and give that component a boundary:

// ✅ the details render now; only the recommendations wait
export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await getProduct(id);
  return (
    <>
      <ProductDetails product={product} />
      <Suspense fallback={<RecommendationsSkeleton />}>
        <Recommendations productId={id} />
      </Suspense>
    </>
  );
}

async function Recommendations({ productId }: { productId: string }) {
  const items = await getRecommendations(productId); // suspends only this boundary
  return <ul>{items.map((item) => <li key={item.id}>{item.name}</li>)}</ul>;
}

That is how it plays out without Cache Components: the page still waits 80 ms for the product, then streams. With cacheComponents: true the build enforces the same idea more strictly: the remaining top-level work must be cacheable too (getProduct under use cache, params covered by generateStaticParams), or it also moves behind a boundary. The next reading covers why.

The Streaming guide applies the same rule to request data in a layout. Don't await cookies() at the top; start it and hand the promise to the component that reads it:

export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  const cookieStore = cookies(); // started, not awaited
  return (
    <div>
      <Nav>
        <Suspense fallback={<p>Loading user…</p>}>
          <UserMenu cookiePromise={cookieStore} />
        </Suspense>
      </Nav>
      {children}
    </div>
  );
}

<Nav> and {children} stay in the shell; only UserMenu waits.

Sibling or nested? Sibling boundaries resolve independently, each in whatever order its data arrives. Nested boundaries reveal in order: the inner fallback can only appear once the outer content has rendered. Use siblings for unrelated panels and nesting for "details, then reviews below them".

A Client Component can wait too. Start the fetch in a Server Component without awaiting it, pass the promise as a prop, and read it in the Client Component with React's use(promise) inside a <Suspense>. The fallback ships in the shell; the data streams in when the promise resolves.

An HTTP response starts with its status line and headers. Once the first chunk of a streamed body has been sent, they're on the wire and can't be taken back. Node shows it plainly:

res.write("<p>shell</p>");   // status + headers are sent with this first chunk
await sleep(100);
res.statusCode = 404;        // no effect: the client already has 200
res.setHeader("X-Late", "1"); // throws ERR_HTTP_HEADERS_SENT

/status: status 200, x-late=null
  +   2ms  <p>shell</p>
  + 103ms  <p>notFound() happened here; setHeader threw: ERR_HTTP_HEADERS_SENT</p>

Next.js lives under the same rule. Streaming starts when a Suspense fallback renders (including one from loading.tsx) or a component suspends under a boundary. After that:

• notFound() can't send a 404. Next streams the not-found UI and injects <meta name="robots" content="noindex"> so search engines skip the URL, but the status stays 200. Some crawlers report it as a "soft 404".
• redirect() can't send a 307. It becomes a client-side redirect: Next injects a <meta http-equiv="refresh"> tag into the stream instead.
• An error thrown mid-stream is caught by the nearest error.tsx, which replaces that section; the rest of the page stays, and the status is still 200.

The trap is how easily a page ends up streaming before its check:

app/posts/[slug]/
  loading.tsx   ← makes the whole page a Suspense boundary
  page.tsx      ← const post = await getPost(slug); if (!post) notFound();

loading.tsx wraps the page, so the moment getPost suspends, the fallback streams with a 200, and a missing post becomes a soft 404 for every crawler and every uptime check.

When the status code matters (missing resources, auth redirects, analytics), decide it before anything streams: a fast existence check at the top of the page with no boundary above it, or earlier still in proxy.ts (rewrite to a not-found route, or return a 404 response) or a next.config redirect. Both run before rendering, while the status line is still unwritten.