Streaming with Suspense

A tea page that arrives in pieces

The tea shop's Mint tea page shows a description that never changes, how many bags are left, and the reviews. The stock and the reviews come from the shop's database, read for each visitor, and each read takes a moment. The visitor shouldn't stare at a blank page until the slowest one is done. Here is the page, as a real Next.js 16.4.3 project: it was built with next build, run with next start, and asked for /teas/mint, and what came back was recorded.

1import { Suspense } from "react";2import { getReviews, getStock } from "@/lib/shop";3 4async function Stock() {5  const stock = await getStock("mint");6  return <p>{stock} bags left</p>;7}8 9async function Reviews() {10  const reviews = await getReviews("mint");11  return (12    <ul>13      {reviews.map((review) => (14        <li key={review}>{review}</li>15      ))}16    </ul>17  );18}19 20export default function MintTeaPage() {21  return (22    <main>23      <h1>Mint tea</h1>24      <p>Fresh mint leaves, picked in May.</p>25      <Suspense fallback={<p>Checking stock…</p>}>26        <Stock />27      </Suspense>28      <h2>Reviews</h2>29      <Suspense fallback={<p>Loading reviews…</p>}>30        <Reviews />31      </Suspense>32    </main>33  );34}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/3cfn99dbrcvvp.js">
    <script src="/_next/static/chunks/1j_b1xq_woyiy.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <!--&-->
    <!--&-->
    <!--&-->
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <!--$?-->
      <template id="B:0"></template>
      <p>Checking stock…</p>
      <!--/$-->
      <h2>Reviews</h2>
      <!--$?-->
      <template id="B:1"></template>
      <p>Loading reviews…</p>
      <!--/$-->
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <!--/&-->
    <script>…</script>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/3cfn99dbrcvvp.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
    <div hidden="" id="S:0">
      <p>4<!-- --> bags left</p>
    </div>
    <script>…</script>
    <div hidden="" id="S:1">
      <ul>
        <li>Cool and fresh.</li>
        <li>Lovely after dinner.</li>
      </ul>
    </div>
    <script>…</script>
    <script>…</script>
  </body>
</html>

app/teas/mint/page.tsx has two async components. Stock, on lines 4 to 7, waits for getStock and says how many bags are left. Reviews, on lines 9 to 18, waits for getReviews and lists them. The page puts each one inside its own Suspense: lines 25 to 27, with the fallback Checking stock…, and lines 29 to 31, with Loading reviews…. Now click lib/shop.ts, the stand-in database. Lines 10 and 16 call connection(), so the reads happen for each request and never during the build. Lines 11 and 17 wait on purpose, the stock a little and the reviews longer, as the comment on lines 7 and 8 says.

The Network tab shows the HTML in the order it arrived. Near the top, inside <main>, are the heading, the description, Checking stock… and Loading reviews…. That first part is the static shell: the static content and anything cached, made during the build, plus a fallback for each Suspense whose content waits for uncached or request-time work, like these two reads. Further down, after the scripts, come two hidden parts: a <div hidden> with 4 bags left, and then another with the two reviews. Each is followed by a small script that React adds, which moves the part into its fallback's place. The Browser tab shows the page after both moves.

Sending one response in pieces, and showing each piece as soon as it arrives, is streaming. Loading UI showed it with one fallback for a whole page. Here the page has two, and each part arrives on its own:

How the pieces arrive

Open the Mint tea page's Terminal tab: ◐ /teas/mint, prerendered as static HTML with dynamic server-streamed content. The shell was made during the build. For each visit, Next.js sends it at once, starts the components that wait, and keeps the response open. Step through one visit:

The status code and the headers leave first, with the shell. Then, as each boundary's content is ready, React renders it to HTML and sends it, with its script. The same response also carries, in other inline scripts, the RSC payload of each part: the description of what the Server Components rendered, which React reads when the page's JavaScript takes over in the browser (How Next.js works introduced it). On a client-side navigation, a click on a link to a page under the same root layout, there's no HTML at all: the router fetches only the RSC payload, and it streams the same way. A link to a page under another root layout loads a whole new document.

Does the stock come first because it's higher on the page? Each version of the page changes one thing. Before you click, guess which hidden part comes first in the Network tab:

1import { connection } from "next/server";2 3function wait(ms: number) {4  return new Promise((resolve) => setTimeout(resolve, ms));5}6 7// A stand-in for the shop's database, read for each request. Each read waits8// on purpose: the stock 200 ms, the reviews 600 ms.9export async function getStock(id: string) {10  await connection();11  await wait(200);12  return id === "mint" ? 4 : 0;13}14 15export async function getReviews(id: string) {16  await connection();17  await wait(600);18  return id === "mint" ? ["Cool and fresh.", "Lovely after dinner."] : [];19}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/3cfn99dbrcvvp.js">
    <script src="/_next/static/chunks/1j_b1xq_woyiy.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <!--&-->
    <!--&-->
    <!--&-->
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <!--$?-->
      <template id="B:0"></template>
      <p>Checking stock…</p>
      <!--/$-->
      <h2>Reviews</h2>
      <!--$?-->
      <template id="B:1"></template>
      <p>Loading reviews…</p>
      <!--/$-->
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <!--/&-->
    <script>…</script>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/3cfn99dbrcvvp.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
    <div hidden="" id="S:0">
      <p>4<!-- --> bags left</p>
    </div>
    <script>…</script>
    <div hidden="" id="S:1">
      <ul>
        <li>Cool and fresh.</li>
        <li>Lovely after dinner.</li>
      </ul>
    </div>
    <script>…</script>
    <script>…</script>
  </body>
</html>

In Reviews ready first, only lines 11 and 17 of lib/shop.ts changed: the waits are swapped. Now the hidden part with the reviews arrives before the one with the stock, although the reviews sit lower on the page. A boundary is sent when its content is ready, not in page order, and one slow part never holds back another.

In One boundary for both, lines 25 to 29 of the page wrap both parts in a single Suspense. The first HTML has one fallback, Loading stock and reviews…. The parts still arrive one by one, but React shows a boundary's content only once everything inside it is ready, so the visitor sees the stock and the reviews together, after the slower read. That's useful when parts belong together and shouldn't pop in one at a time. React's Streaming lesson shows where these pieces come from in React itself.

loading.tsx or Suspense?

Loading UI showed that loading.tsx is a Suspense around the whole page. It streams the same way. The difference is what it puts behind the fallback. In this version, the page awaits both reads itself, with Promise.all on line 4 of app/teas/mint/page.tsx, and app/teas/mint/loading.tsx gives the whole page one loading state:

1export default function Loading() {2  return <p>Loading the tea page…</p>;3}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/3cfn99dbrcvvp.js">
    <script src="/_next/static/chunks/1j_b1xq_woyiy.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <!--&-->
    <!--&-->
    <!--&-->
    <!--$?-->
    <template id="B:0"></template>
    <p>Loading the tea page…</p>
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <!--/&-->
    <script>…</script>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/3cfn99dbrcvvp.js" async=""></script>
    <div hidden="" id="S:0">
      <template id="P:1"></template>
      <!--$-->
      <!--/$-->
    </div>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
    <div hidden="" id="S:1">
      <main>
        <h1>Mint tea</h1>
        <p>Fresh mint leaves, picked in May.</p>
        <p>4<!-- --> bags left</p>
        <h2>Reviews</h2>
        <ul>
          <li>Cool and fresh.</li>
          <li>Lovely after dinner.</li>
        </ul>
      </main>
    </div>
    <script>…</script>
    <script>…</script>
  </body>
</html>

The first part of the HTML holds Loading the tea page… and nothing else of the page: not the heading, not the description, though neither of them waits for anything. They're inside the page, and the page waits. Everything arrives later, in a hidden part further down. Each row compares the two ways on this page:

The docs recommend a Suspense close to the data. A loading.tsx high in the tree is a valid boundary, but then the whole page shows one loading state instead of streaming part by part. The two also work together: a loading.tsx for the moment the page itself waits, and a Suspense inside the page for the parts that wait longer.

Where to place a boundary

A boundary covers the waits inside it. So it goes above the component that waits, in the component that renders it. The most common mistake is the opposite: a Suspense inside the async component, around its own JSX. Pick each version:

1import { Suspense } from "react";2import { getReviews, getStock } from "@/lib/shop";3 4async function Stock() {5  const stock = await getStock("mint");6  return <p>{stock} bags left</p>;7}8 9async function Reviews() {10  const reviews = await getReviews("mint");11  return (12    <Suspense fallback={<p>Loading reviews…</p>}>13      <ul>14        {reviews.map((review) => (15          <li key={review}>{review}</li>16        ))}17      </ul>18    </Suspense>19  );20}21 22export default function MintTeaPage() {23  return (24    <main>25      <h1>Mint tea</h1>26      <p>Fresh mint leaves, picked in May.</p>27      <Suspense fallback={<p>Checking stock…</p>}>28        <Stock />29      </Suspense>30      <h2>Reviews</h2>31      <Reviews />32    </main>33  );34}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...Error: Route "/teas/mint": Next.js encountered uncached or runtime data during prerendering. `fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience. Ways to fix this:  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access  - [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"` (does not apply to `connection()`)  - [block] Set `export const instant = false` to allow a blocking route Learn more: https://nextjs.org/docs/messages/blocking-prerender-dynamic    at main (<anonymous>)    at body (<anonymous>)    at html (<anonymous>)To get a more detailed stack trace and pinpoint the issue, try one of the following:  - Start the app in development mode by running `next dev`, then open "/teas/mint" in your browser to investigate the error.  - Rerun the production build with `next build --debug-prerender` to generate better stack traces.Error occurred prerendering page "/teas/mint". Read more: https://nextjs.org/docs/messages/prerender-errorExport encountered an error on /teas/mint/page: /teas/mint, exiting the build.⨯ Next.js build worker exited with code: 1 and signal: null

In Inside the component, Reviews waits on line 10, and only then returns the Suspense on line 12. While it waits, that Suspense doesn't exist yet. React looks up the tree for a boundary, and line 31 of the page renders <Reviews /> with none around it. With Cache Components on, the build stops: Next.js encountered uncached or runtime data during prerendering. The first fix the error lists, [stream], is a Suspense around the data access, which means above the component that waits.

In Above the component, the Suspense on lines 29 to 31 wraps <Reviews /> in the page, and the first HTML has the heading, the description and both fallbacks. In loading.tsx for the page, the boundary is above the whole page, so nothing of the page is in the first part.

The same goes for anything that waits. An await at the top of a page or a layout puts everything below it behind the nearest boundary above. The docs call the fix pushing dynamic access down: let the component that needs the data await it, and wrap that component. Boundaries can also nest: an inner Suspense shows its own fallback once the outer one's content has arrived.

Passing a promise to a Client Component

A Client Component can't be async, but it can wait for a promise with use. Composing Server and Client Components showed the pattern: a Server Component starts a read without await and passes the promise down. It streams like any other part. Here the reviews get a Hide reviews button:

1import { Suspense } from "react";2import { getReviews, getStock } from "@/lib/shop";3import ReviewList from "./review-list";4 5async function Stock() {6  const stock = await getStock("mint");7  return <p>{stock} bags left</p>;8}9 10export default function MintTeaPage() {11  const reviews = getReviews("mint");12  return (13    <main>14      <h1>Mint tea</h1>15      <p>Fresh mint leaves, picked in May.</p>16      <Suspense fallback={<p>Checking stock…</p>}>17        <Stock />18      </Suspense>19      <h2>Reviews</h2>20      <Suspense fallback={<p>Loading reviews…</p>}>21        <ReviewList reviews={reviews} />22      </Suspense>23    </main>24  );25}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/3cfn99dbrcvvp.js">
    <script src="/_next/static/chunks/1j_b1xq_woyiy.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <script src="/_next/static/chunks/3sh19eyk9agcw.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <!--&-->
    <!--&-->
    <!--&-->
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <!--$?-->
      <template id="B:0"></template>
      <p>Checking stock…</p>
      <!--/$-->
      <h2>Reviews</h2>
      <!--$?-->
      <template id="B:1"></template>
      <p>Loading reviews…</p>
      <!--/$-->
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <!--/&-->
    <script>…</script>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/3cfn99dbrcvvp.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
    <div hidden="" id="S:0">
      <p>4<!-- --> bags left</p>
    </div>
    <script>…</script>
    <div hidden="" id="S:1">
      <button>Hide reviews</button>
      <ul>
        <li>Cool and fresh.</li>
        <li>Lovely after dinner.</li>
      </ul>
    </div>
    <script>…</script>
    <script>…</script>
  </body>
</html>

Line 11 of app/teas/mint/page.tsx calls getReviews("mint") without await, so the page itself never waits. Line 21 passes the promise to ReviewList, inside the Suspense on lines 20 to 22. In app/teas/mint/review-list.tsx, line 6 reads it with use(reviews), which suspends ReviewList until the promise settles. The Suspense has to sit above the component that calls use(), as for any component that waits. The promise must settle to a value that can be serialized, sent from the server to the browser as data, like the props in Composing Server and Client Components: here a string[], a list of strings, which is. The Network tab shows the same pieces as the first Mint tea page: the shell with both fallbacks, then the stock, then a hidden part with the button and both reviews.

Open the Steps tab, recorded in real Chrome: clicking Hide reviews hides the list, with no request, because open is state in the browser. The recording also checked the page's JavaScript files: they contain Hide reviews, from the Client Component's code, but not Cool and fresh. The reviews are data. They came with the page's response, not with its code.

Streaming and search engines

A response starts with its status code and headers. With streaming, they leave together with the first part, before the parts that wait have run:

So a page can't change its status after streaming has started. When a streamed part calls notFound(), the response stays 200, and Next.js adds a noindex tag so search engines leave the page out, as Not found, forbidden and unauthorized recorded. A redirect() there can't send a 307 either: the response stays 200 and tells the browser to go to the new address, as Redirects showed. So a check that must answer a real 404 has to finish before the response starts to stream. A page can call notFound() before it returns any Suspense and before the response starts, or the check can run earlier still, in proxy.ts, which the docs suggest as one option.

The content is a different story. Every part is in the same HTML response, so a program that reads the whole response gets the stock and the reviews too. The docs say streaming doesn't hurt search: the page is still rendered on the server. Some bots need more. Programs that make link previews often read only the <head> and run no JavaScript. Next.js calls them HTML-limited bots, and makes them wait for generateMetadata, so the title is in the <head>: that's streaming metadata, from the Metadata API lesson.

The recorder also asked for the Mint tea page as Slackbot, one of those bots. Pick from Slackbot in the Network tab of the Mint tea page's recording, the one with a Suspense above each part. In this recording, Slackbot received the same visible markup in its first part as Chrome did, with both fallbacks, then the stock, then the reviews. Its response headers are shorter, though: the three whose names start with x-nextjs- in Chrome's response aren't there, so this first part was rendered for Slackbot's request rather than sent from the prerendered shell.

That matches what the docs say about these bots: with Cache Components, HTML-limited bots skip the prerendered shell, and Next.js renders the page for their request, so it can put the metadata in the <head>, and the rest can still stream. This page has no generateMetadata, so nothing held the response back. Each row is one part of a response:

Planning the Mint tea page's boundaries

Planning boundaries comes down to a few questions for each part of a page:

• Does it wait for anything read per request? If not, leave it outside every boundary: it goes in the static shell.
• What should the visitor see meanwhile? That's the fallback. Give it the part's shape, as a skeleton does, so nothing jumps.
• Should it appear with the parts next to it, or on its own? One boundary for parts that belong together; one each for parts that don't.
• Does the page need a real status code? Finish that check before the response starts to stream: before the first Suspense, or in proxy.ts.

Sort these parts of the Mint tea page's versions: are they in the first part, or streamed in later?

Common mix-ups

• "Streaming needs code of its own to send HTML in pieces." No. A Suspense or a loading.tsx is all it takes. Next.js and React do the sending.
• "Parts arrive in the order they appear on the page." No. With the waits swapped, the reviews arrived before the stock.
• "A Suspense inside the component that waits covers the wait." No. It only exists after the wait. The recorded build stopped.
• "Each part inside one boundary shows as soon as it arrives." No. A boundary shows its content once everything inside it is ready.
• "Streamed content is hidden from search engines." No. It's in the same HTML response. Slackbot's response held the reviews too.
• "A streamed page can still answer 404." Not once the first part has left. It stays 200, with a noindex tag.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints. They use the same stand-in database: the stock waits less than the reviews, unless the exercise says otherwise.

import { Suspense } from "react";
import { getReviews, getStock } from "@/lib/shop";

async function Stock() {
  const stock = await getStock("mint");
  return <p>{stock} bags left</p>;
}

async function Reviews() {
  const reviews = await getReviews("mint");
  return (
    <ul>
      {reviews.map((review) => (
        <li key={review}>{review}</li>
      ))}
    </ul>
  );
}

export default function MintTeaPage() {
  return (
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <Suspense fallback={<p>Checking stock…</p>}>
        <Stock />
      </Suspense>
      <h2>Reviews</h2>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <Reviews />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, getStock } from "@/lib/shop";

async function Stock() {
  const stock = await getStock("mint");
  return <p>{stock} bags left</p>;
}

async function Reviews() {
  const reviews = await getReviews("mint");
  return (
    <ul>
      {reviews.map((review) => (
        <li key={review}>{review}</li>
      ))}
    </ul>
  );
}

export default function MintTeaPage() {
  return (
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <Suspense fallback={<p>Loading stock and reviews…</p>}>
        <Stock />
        <h2>Reviews</h2>
        <Reviews />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, getStock } from "@/lib/shop";

async function Stock() {
  const stock = await getStock("mint");
  return <p>{stock} bags left</p>;
}

async function Reviews() {
  const reviews = await getReviews("mint");
  return (
    <Suspense fallback={<p>Loading reviews…</p>}>
      <ul>
        {reviews.map((review) => (
          <li key={review}>{review}</li>
        ))}
      </ul>
    </Suspense>
  );
}

export default function MintTeaPage() {
  return (
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <Suspense fallback={<p>Checking stock…</p>}>
        <Stock />
      </Suspense>
      <h2>Reviews</h2>
      <Reviews />
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, getStock } from "@/lib/shop";

async function Stock() {
  const stock = await getStock("mint");
  return <p>{stock} bags left</p>;
}

async function Reviews() {
  const reviews = await getReviews("mint");
  return (
    <ul>
      {reviews.map((review) => (
        <li key={review}>{review}</li>
      ))}
    </ul>
  );
}

export default function MintTeaPage() {
  return (
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <Suspense fallback={<p>Checking stock…</p>}>
        <Stock />
      </Suspense>
      <h2>Reviews</h2>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <Reviews />
      </Suspense>
    </main>
  );
}

import { connection } from "next/server";

function wait(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// A stand-in for the shop's database, read for each request. Each read waits
// on purpose: the stock 600 ms, the reviews 200 ms.
export async function getStock(id: string) {
  await connection();
  await wait(600);
  return id === "mint" ? 4 : 0;
}

export async function getReviews(id: string) {
  await connection();
  await wait(200);
  return id === "mint" ? ["Cool and fresh.", "Lovely after dinner."] : [];
}

import { getReviews, getStock } from "@/lib/shop";

export default async function MintTeaPage() {
  const [stock, reviews] = await Promise.all([getStock("mint"), getReviews("mint")]);
  return (
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <p>{stock} bags left</p>
      <h2>Reviews</h2>
      <ul>
        {reviews.map((review) => (
          <li key={review}>{review}</li>
        ))}
      </ul>
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, getStock } from "@/lib/shop";

async function Stock() {
  const stock = await getStock("mint");
  return <p>{stock} bags left</p>;
}

async function Reviews() {
  const reviews = await getReviews("mint");
  return (
    <ul>
      {reviews.map((review) => (
        <li key={review}>{review}</li>
      ))}
    </ul>
  );
}

export default function MintTeaPage() {
  return (
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <Suspense fallback={<p>Checking stock…</p>}>
        <Stock />
      </Suspense>
      <h2>Reviews</h2>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <Reviews />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, getStock } from "@/lib/shop";

async function Stock() {
  const stock = await getStock("mint");
  return <p>{stock} bags left</p>;
}

async function Reviews() {
  const reviews = await getReviews("mint");
  return (
    <ul>
      {reviews.map((review) => (
        <li key={review}>{review}</li>
      ))}
    </ul>
  );
}

export default function MintTeaPage() {
  return (
    <main>
      <h1>Mint tea</h1>
      <p>Fresh mint leaves, picked in May.</p>
      <Suspense fallback={<p>Checking stock…</p>}>
        <Stock />
      </Suspense>
      <h2>Reviews</h2>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <Reviews />
      </Suspense>
    </main>
  );
}

Check your understanding

Key takeaways

• Streaming sends one HTML response in pieces: the static shell first, with the static and cached content and a fallback for each boundary that waits for uncached or request-time work, then that boundary's content when it's ready.
• Parts arrive in the order their data is ready, not in page order. A boundary shows its content once everything inside it is ready.
• Put each Suspense above the component that waits. One inside it comes too late: with Cache Components, the build stops.
• loading.tsx is one boundary around the whole page. A Suspense close to the data lets the rest of the page show at once.
• A promise passed to a Client Component streams the same way; the boundary goes above the component that calls use().
• The status code leaves with the first part. Every part is in the HTML response, and HTML-limited bots get their metadata in the <head>.

Coming next: Fetching in the browser. It covers the data that really belongs to the browser, like live updates and infinite lists.