Streaming & Suspense

🔍 What Is It?

Streaming in Next.js uses HTTP streaming + React Suspense to send HTML progressively:

• →The page shell (layout, fast content) is sent immediately
• →Slow sections (database queries, external APIs) stream in as they complete
• →Each Suspense boundary is an independent streaming unit
• →Users see and interact with fast content while slow content loads

Without streaming: User waits 2 seconds for ALL data before seeing ANY content.

With streaming: User sees the page shell in 100ms, fast sections in 200ms, slow sections in 2 seconds.

🎯 Why Do We Need It?

Traditional SSR blocks on the slowest data fetch. A page with 5 data fetches waits for all 5 before sending any HTML.

Streaming eliminates this:

• →Faster Time to First Byte (TTFB) — page shell sent immediately
• →Better perceived performance — users see content progressively
• →Parallel data loading — independent sections load simultaneously
• →Better UX — skeleton loaders instead of blank pages

🏗️ What Happens in Real Projects?

Streaming in a dashboard:

• →Page shell (header, sidebar, layout) — instant, 0ms
• →User greeting — 50ms (fast session lookup)
• →Recent activity — 150ms (simple DB query)
• →Revenue chart — 800ms (complex aggregation)
• →AI insights — 2000ms (LLM API call)

With Suspense, all five load in parallel and stream in as ready. Without Suspense, the user waits 2000ms for everything.

⚙️ How It Works

Streaming rendering pipeline:

1. Request arrives
2. Next.js renders the page tree synchronously until it hits a Suspense boundary
3. Sends the outer HTML (layout, fast content) to the browser immediately
4. Browser displays the page shell + skeleton fallbacks
5. Async Server Components inside Suspense boundaries continue rendering
6. As each completes, Next.js streams the HTML chunk to the browser
7. Browser replaces the skeleton with the real content (no JS re-render)

💻 Example

Streaming with Suspense Boundaries — A dashboard that streams each section independently for maximum perceived performance.

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

// Each component fetches its own data
async function RevenueChart() {
  const data = await getRevenueData(); // 800ms
  return <Chart data={data} />;
}

async function RecentOrders() {
  const orders = await getRecentOrders(); // 200ms
  return <OrdersList orders={orders} />;
}

async function UserGreeting() {
  const user = await getUser(); // 50ms
  return <h1>Welcome back, {user.name}</h1>;
}

// The page itself has NO awaits — it renders immediately
export default function DashboardPage() {
  return (
    <div className="space-y-6">
      {/* Streams in at 50ms */}
      <Suspense fallback={<GreetingSkeleton />}>
        <UserGreeting />
      </Suspense>

      <div className="grid grid-cols-2 gap-6">
        {/* Streams in at 200ms */}
        <Suspense fallback={<OrdersSkeleton />}>
          <RecentOrders />
        </Suspense>

        {/* Streams in at 800ms */}
        <Suspense fallback={<ChartSkeleton />}>
          <RevenueChart />
        </Suspense>
      </div>
    </div>
  );
}

🤔 Common Confusions

🚨 Common Production Issues

✅ Best Practices

🏛️ Architect's Note

💬 Frequently Asked Questions

🎯 Key Takeaways

🔗 Related Topics

🎯 Practice this topic in interviews

↗ Where this topic fits