0Pricing
Next.js 15 Fullstack (App Router + Server Actions) · 课时

Suspense 边界与组件级流式传输

将加载缓慢的数据组件包裹在 Suspense 中，使其独立于静态外壳进行流式传输。

Suspense 边界与组件级流式传输 是 CoddyKit 上的免费 Next.js 15 Fullstack (App Router + Server Actions) 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Next.js 15 Fullstack (App Router + Server Actions) 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Next.js 15 Fullstack (App Router + Server Actions) 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Stream at the Component Level?

In the App Router, a page can contain both fast static content (header, nav, layout shell) and slow data-dependent content (a dashboard widget that hits a third-party API).

Without streaming, the whole page waits for the slowest fetch before anything renders. That hurts perceived performance.

Component-level streaming lets Next.js send the static shell immediately, then stream each slow part in as its data resolves. The tool that enables this is React's <Suspense> boundary.

The Blocking Problem

Here a single async Server Component awaits a slow query. Because the page awaits before returning JSX, the user sees nothing until the 2-second fetch finishes.

The fast parts of the page (title, layout) are held hostage by the slow part.

// app/dashboard/page.tsx
async function getStats() {
  // simulates a slow 2s upstream call
  await new Promise((r) => setTimeout(r, 2000));
  return { revenue: 4200, orders: 87 };
}

export default async function DashboardPage() {
  const stats = await getStats(); // blocks the WHOLE page
  return (
    <main>
      <h1>Dashboard</h1>
      <p>Revenue: {stats.revenue}</p>
      <p>Orders: {stats.orders}</p>
    </main>
  );
}

Extract the Slow Part into Its Own Component

The first step to streaming is isolation: move the awaited data into a separate async Server Component.

The page itself no longer awaits anything, so its static shell can render instantly. The slow work now lives inside <Stats />.

// app/dashboard/stats.tsx
async function getStats() {
  await new Promise((r) => setTimeout(r, 2000));
  return { revenue: 4200, orders: 87 };
}

export async function Stats() {
  const stats = await getStats();
  return (
    <section>
      <p>Revenue: {stats.revenue}</p>
      <p>Orders: {stats.orders}</p>
    </section>
  );
}

Wrap It in a Suspense Boundary

Now wrap the slow component in <Suspense> and give it a fallback. Next.js renders the shell plus the fallback immediately, then streams the real component over the same HTTP response once its data resolves.

  • fallback shows while the boundary's data is pending.
  • Everything outside the boundary is sent right away.
// app/dashboard/page.tsx
import { Suspense } from 'react';
import { Stats } from './stats';

export default function DashboardPage() {
  return (
    <main>
      <h1>Dashboard</h1> {/* sent immediately */}
      <Suspense fallback={<p>Loading stats…</p>}>
        <Stats /> {/* streamed in when ready */}
      </Suspense>
    </main>
  );
}

A Good Fallback Is a Skeleton

The fallback should match the shape of the final content to avoid layout shift. A skeleton placeholder is far better than a bare spinner because it reserves space and signals what's coming.

Keep skeletons as plain, fast Client or Server Components with no data dependencies.

// app/dashboard/stats-skeleton.tsx
export function StatsSkeleton() {
  return (
    <section aria-hidden className="animate-pulse">
      <div className="h-6 w-40 rounded bg-gray-200" />
      <div className="mt-2 h-6 w-32 rounded bg-gray-200" />
    </section>
  );
}

// usage:
// <Suspense fallback={<StatsSkeleton />}>
//   <Stats />
// </Suspense>

Multiple Independent Boundaries

Each <Suspense> streams independently. If you have several slow widgets, give each its own boundary so a slow one never blocks a fast one.

Below, RecentOrders may resolve in 300ms while Revenue takes 2s — and each appears the moment it's ready, in any order.

import { Suspense } from 'react';
import { Revenue } from './revenue';
import { RecentOrders } from './recent-orders';
import { RevenueSkeleton, OrdersSkeleton } from './skeletons';

export default function DashboardPage() {
  return (
    <main>
      <h1>Dashboard</h1>
      <Suspense fallback={<RevenueSkeleton />}>
        <Revenue />
      </Suspense>
      <Suspense fallback={<OrdersSkeleton />}>
        <RecentOrders />
      </Suspense>
    </main>
  );
}

Boundary Granularity Is a Design Choice

You decide how to group slow components under boundaries:

  • One boundary per widget → each widget pops in on its own (best for unrelated data).
  • One boundary around a group → the group appears together once all its data resolves (good when a coordinated reveal looks cleaner).

A shared boundary streams only when the slowest child inside it is ready, so don't accidentally couple a fast widget to a slow one.

Passing Promises Down with the `use` Hook

An alternative pattern: start the fetch in the parent without awaiting, then pass the promise to a child that unwraps it with React's use hook. The child must be inside a <Suspense> boundary, which suspends on the pending promise.

This lets the parent kick off several requests in parallel before any of them block.

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

function getStats() {
  return new Promise<{ revenue: number }>((r) =>
    setTimeout(() => r({ revenue: 4200 }), 2000),
  );
}

export default function Page() {
  const statsPromise = getStats(); // NOT awaited
  return (
    <Suspense fallback={<p>Loading…</p>}>
      <Stats statsPromise={statsPromise} />
    </Suspense>
  );
}

The Client Component That Reads the Promise

The child uses use(promise) to read the resolved value. When the promise is pending, use suspends and the nearest <Suspense> shows its fallback.

use can be called in a Client Component, making it the idiomatic way to stream a server-started promise into interactive UI.

// app/dashboard/stats.tsx
'use client';
import { use } from 'react';

export function Stats({
  statsPromise,
}: {
  statsPromise: Promise<{ revenue: number }>;
}) {
  const stats = use(statsPromise); // suspends until resolved
  return <p>Revenue: {stats.revenue}</p>;
}

loading.tsx Is a Route-Level Suspense

A file named loading.tsx in a route segment is sugar: Next.js automatically wraps that segment's page.tsx in a <Suspense> using the loading file as the fallback.

  • loading.tsx → streams the whole page while it loads (one big boundary).
  • Manual <Suspense> → streams parts of the page independently.

Use loading.tsx for the coarse first paint, and inline <Suspense> for fine-grained component streaming inside the page.

// app/dashboard/loading.tsx
export default function Loading() {
  return <p>Loading dashboard…</p>;
}

Don't Forget: Pure Functions Can Be Tested in Isolation

The data-shaping logic that feeds your streamed components is just plain TypeScript — keep it pure so you can unit-test it without a server. Here a standalone summarizer that any judge can run.

type Order = { id: number; total: number };

function summarize(orders: Order[]): { count: number; revenue: number } {
  const revenue = orders.reduce((sum, o) => sum + o.total, 0);
  return { count: orders.length, revenue };
}

const orders: Order[] = [
  { id: 1, total: 1200 },
  { id: 2, total: 3000 },
];

const result = summarize(orders);
console.log(`Orders: ${result.count}, Revenue: ${result.revenue}`);

Quick Check

You have a dashboard page with a fast header and two slow widgets: <Revenue /> (~2s) and <Orders /> (~300ms). You want the header to appear instantly and each widget to appear the moment its own data is ready, independently.

Recap

Key takeaways for component-level streaming:

  • Isolate slow data fetches into their own async Server Components.
  • Wrap each in <Suspense fallback={…}> — the shell and everything outside the boundary stream immediately.
  • Use skeleton fallbacks that match final shape to avoid layout shift.
  • Multiple boundaries stream independently; a shared boundary waits for its slowest child.
  • Pass an un-awaited promise down and read it with the use hook for parallel, streamed data.
  • loading.tsx is an automatic route-level Suspense for coarse first paint; inline <Suspense> handles fine-grained streaming.

常见问题解答

「Suspense 边界与组件级流式传输」课时是免费的吗？

是的 — 「Suspense 边界与组件级流式传输」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Next.js 15 Fullstack (App Router + Server Actions) 课程的其余内容，请升级到 CoddyKit PRO。 Next.js 15 Fullstack (App Router + Server Actions) 课程共包含 4 节课。

「Suspense 边界与组件级流式传输」这节课中我会学到什么？

将加载缓慢的数据组件包裹在 Suspense 中，使其独立于静态外壳进行流式传输。 你通过在浏览器中直接运行的动手代码来练习 Next.js 15 Fullstack (App Router + Server Actions)，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Next.js 15 Fullstack (App Router + Server Actions) 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Next.js 15 Fullstack (App Router + Server Actions) 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。

「Suspense 边界与组件级流式传输」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Next.js 15 Fullstack (App Router + Server Actions) 课中编写并运行代码吗？

能。每节 Next.js 15 Fullstack (App Router + Server Actions) 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. Suspense 边界与组件级流式传输
  2. 打造有意义的 loading.tsx 与骨架屏
  3. 部分预渲染：静态外壳与动态空洞
  4. 流式传输陷阱：布局偏移与瀑布流
← 返回 Next.js 15 Fullstack (App Router + Server Actions)