Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 72 ยท Rendering Strategies

Streaming with Suspense

Stop one slow query from blocking a whole page: learn Suspense boundaries, loading.tsx, streamed HTML and progressive rendering in Next.js with live stand-ins.

Imagine a product page where the title and price come from a fast query, but the reviews list comes from a slow service that takes two seconds. If the server waits for everything before sending anything, every visitor stares at a blank tab for two seconds, even though most of the page was ready almost at once.

Streaming fixes this. The server sends the HTML that is ready immediately, leaves a placeholder where the slow part will go, and sends the rest later through the same HTTP response. React swaps each placeholder for the real content as it arrives. The tool you use to mark "this part may be slow" is the Suspense component from React. This lesson shows how to place boundaries, how loading.tsx does it for you, what actually travels over the wire, and the mistakes that quietly turn streaming off.

The idea in four steps

A page with a slow part

Fast parts Title, price and layout are ready at once.
Slow part Reviews wait on a slow service.

Without streaming, the slow part holds back everything.

1 / 4

Suspense boundaries in a Server Component page

In the App Router, a Server Component can be an async function. A Suspense boundary around such a component tells Next.js: "do not wait for this one; show the fallback and stream the result when it is done."

TSX
// app/product/[id]/page.tsx
import { Suspense } from 'react';
import { getProduct, getReviews } from '@/lib/data/products';

export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await getProduct(id); // fast: part of the first chunk

  return (
    <main>
      <h1>{product.name}</h1>
      <p>Price: ${product.price}</p>
      <Suspense fallback={<p>Loading reviews...</p>}>
        <Reviews productId={id} />
      </Suspense>
    </main>
  );
}

async function Reviews({ productId }: { productId: string }) {
  const reviews = await getReviews(productId); // slow: streamed later
  return (
    <ul>
      {reviews.map((review) => (
        <li key={review.id}>{review.text}</li>
      ))}
    </ul>
  );
}

The key detail is where the slow await lives. It sits inside Reviews, which is inside the boundary. If you moved await getReviews(id) up into ProductPage, the page function itself would wait for it, and nothing could be sent before it finished. A boundary only helps for work that happens in components below it.

You can use several boundaries on one page. Each streams independently, so a fast widget appears as soon as it is ready, and a slow widget does not delay its neighbors.

loading.tsx: a boundary for a whole route

Writing a boundary by hand for every page would be tedious, so Next.js has a special file. If a route segment contains loading.tsx, Next.js wraps that segment's page.tsx (and everything below it) in a Suspense boundary whose fallback is your loading component:

TSX
// app/dashboard/loading.tsx
export default function Loading() {
  return <div className="skeleton">Loading your dashboard...</div>;
}

The layout that sits above loading.tsx is not inside the boundary, so the navigation bar and sidebar appear immediately while the page content streams in. The same file also makes client-side navigation feel instant, because the fallback shows while the next page loads. loading.tsx, error.tsx and not-found.tsx covers the file conventions in detail. Use loading.tsx for a quick route-wide skeleton, and explicit Suspense boundaries when you want finer control inside a page.

What travels over the wire

Streaming relies on a plain HTTP feature: the server can send a response in several pieces before it has finished. React's server renderer writes the shell first. For each boundary that is still waiting it writes the fallback inside special markers. When the data arrives, it writes the finished HTML into a hidden container plus a very small inline script that moves it into the right place.

React's own renderToReadableStream function does exactly this. Next.js uses the same machinery behind the scenes, so reading a stream yourself is a faithful way to see it. The first live example renders a product page with two boundaries that resolve at different times and prints a description of each chunk it receives.

Reading a streamed page

The first piece already contains the heading, the price and both fallbacks. The reviews and the related items arrive afterwards, in the order they finish. Notice the stand-in uses React's real renderer, but a real Next.js server also adds its own framework data to each chunk (the RSC payload, covered in Inside the RSC Payload).

Progressive rendering you can feel

Streaming is easiest to understand by watching boundaries resolve. The second example runs React 19's Suspense in the browser. Three widgets load with different delays. In one boundary mode they share a single Suspense, so the page stays on one skeleton until the slowest widget is ready. In separate boundaries mode each widget has its own, so each appears as soon as its own data arrives. Press Reload to run it again.

One boundary or three?

With one boundary, the profile (ready after 200 ms) has to wait for the ads (900 ms), so the visitor sees only a single skeleton for almost a second. With separate boundaries the profile shows up early and the feed follows. Choosing boundaries is a design decision: group things that should appear together, and separate things that are independent.

Real or stand-in? The Suspense, loading.tsx and async Server Component code in the first half of this lesson is real Next.js, shown read-only. The two live examples use React's real Suspense and use, but in the browser or through renderToReadableStream rather than inside a Next.js server, and the delays are simulated with timers.

Avoiding accidental blocking

Streaming only works when the slow work is inside a boundary. These are the common ways to defeat it:

  • Awaiting in the page. Any await in page.tsx or a layout above the boundary delays the first byte. Fetch only what the first chunk needs there.
  • Fetching in a parent and rendering a child that waits again. This creates a waterfall (see Data Access Layers and ORMs); start independent requests together.
  • One giant boundary. It behaves like no streaming for everything inside it.
  • Boundaries that flash. If data is usually ready within a few milliseconds, a skeleton that appears and vanishes is worse than waiting. Reserve boundaries for parts that are genuinely slow.
  • Skeletons of the wrong size. A fallback that is much shorter than the real content pushes the page around when it arrives. Give the skeleton the same height.

There is also a hard limit to remember: the HTTP status code is sent with the first bytes. Once streaming has started, the server cannot turn the response into a different status. That is one reason checks that must change the response, such as authentication redirects, usually happen early, before the slow content, which Middleware and the Proxy File and Authorization and Data Security discuss.

React also benefits on the client. It can hydrate the pieces that have arrived without waiting for the rest, and it prioritizes the part a visitor clicks first. That is called selective hydration, and it is part of why streaming improves interactivity, not only the first paint.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a Suspense boundary do in a streamed page?

    The boundary lets the server send the rest of the page immediately and fill in the suspended part when its data arrives.
  2. 2. A page awaits a slow query at the top of page.tsx, and the slow component is wrapped in Suspense. What happens?

    A boundary only helps for work done in components below it. An await in the page function itself delays the first byte.
  3. 3. What does adding loading.tsx to a route segment do?

    loading.tsx is a convention that creates a boundary around the page. Layouts above it are not inside the boundary, so they show immediately.
  4. 4. Why can't a streamed response change its HTTP status code halfway through?

    Headers and status are sent before the body begins streaming, so checks that must change the response need to happen early.

Summary

  • Streaming sends the ready parts of a page first and the slow parts later in the same response, so one slow query no longer blocks everything.
  • Mark slow parts with a Suspense boundary and a fallback; the slow await must live inside a component below the boundary.
  • loading.tsx wraps a route segment's page in a boundary automatically, and the layout above it shows instantly.
  • Separate boundaries let independent parts appear independently; one big boundary waits for the slowest part.
  • Avoid awaiting in the page, waterfalls, flashing skeletons and size-changing fallbacks, and remember the status code is fixed once streaming begins.

Next: Partial Prerendering