Parallel and sequential fetching

A tea page that waits in line

The tea shop's Tea of the week page shows a tea and its reviews. Both come from the shop's database, read in a Server Component, as Fetching data in Server Components showed, and each read takes a moment. If the page asks for the tea, waits for the answer, and only then asks for the reviews, the two waits add up. Here is that page, as a real Next.js 16.4.3 project: it was built with next build and run with next start, and what happened was recorded.

1import { Suspense } from "react";2import { getReviews, getTea } from "./_data/shop";3 4async function MintTea() {5  const tea = await getTea("mint");6  const reviews = await getReviews("mint");7  return (8    <section>9      <h2>10        {tea.name}: ${tea.price}11      </h2>12      <ul>13        {reviews.map((review) => (14          <li key={review}>{review}</li>15        ))}16      </ul>17    </section>18  );19}20 21export default function Home() {22  return (23    <main>24      <h1>Tea of the week</h1>25      <Suspense fallback={<p>Loading the tea…</p>}>26        <MintTea />27      </Suspense>28    </main>29  );30}

$ 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 ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ◐ /└ ○ /_not-found ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ Readyquery 1 starts: tea mintquery 1 ends: tea mintquery 2 starts: reviews of mintquery 2 ends: reviews of mint

In app/page.tsx, line 5 waits for getTea("mint"), and line 6 waits for getReviews("mint"). An await pauses MintTea until the promise settles, so line 6 doesn't even run until the tea has arrived. Lines 25 to 27 put MintTea inside a Suspense, so the heading shows while it waits, as Loading UI showed.

Now click app/_data/shop.ts, a stand-in for the database. Line 8 calls connection(), which tells Next.js to run what follows for each request, never during the build. Line 9 counts the queries. Line 11 prints a line when a query starts, and line 13 prints another when it ends. Line 12 waits in between, the same for every query, on purpose: it plays the database.

The Terminal tab shows what next build printed, then what next start printed while it answered one visit to /. Read the four query lines in order. Query 1 starts and ends, and only then does query 2 start. The lines don't measure time; their order is what tells the story. The reviews never needed the tea, and yet they waited for it. Requests that run one after another, each starting only when the one before it has ended, are called a waterfall, after the shape their bars make on a timeline:

Start both, then wait for both: Promise.all

A promise starts its work when the function is called, not when something awaits it. So the fix is to call both functions first. Promise.all takes a list of promises and gives back one promise, which settles once all of them have. Pick each version and compare the terminals:

1import { Suspense } from "react";2import { getReviews, getTea } from "./_data/shop";3 4async function MintTea() {5  const tea = await getTea("mint");6  const reviews = await getReviews("mint");7  return (8    <section>9      <h2>10        {tea.name}: ${tea.price}11      </h2>12      <ul>13        {reviews.map((review) => (14          <li key={review}>{review}</li>15        ))}16      </ul>17    </section>18  );19}20 21export default function Home() {22  return (23    <main>24      <h1>Tea of the week</h1>25      <Suspense fallback={<p>Loading the tea…</p>}>26        <MintTea />27      </Suspense>28    </main>29  );30}

$ 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 ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ◐ /└ ○ /_not-found ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ Readyquery 1 starts: tea mintquery 1 ends: tea mintquery 2 starts: reviews of mintquery 2 ends: reviews of mint

In the Promise.all version, line 5 calls getTea("mint") and getReviews("mint") before its one await. Both queries start, and then the component waits for both. The terminal prints query 1 starts, query 2 starts, and only then the two ends. The page is the same in both versions: open the Browser tab to see Mint tea: $3 and both reviews. Sequential vs parallel, in the JavaScript course, shows the same idea without Next.js.

Promise.all isn't the only way to write it. Calling both functions on two lines, keeping their promises, and awaiting them afterwards starts both queries just the same. Promise.all is simply the tidy way to wait for a list.

Two things to know about it. If one of the promises rejects, Promise.all rejects too, and the error goes to the nearest error.tsx, as any error in a Server Component does. When one failed read shouldn't hide the other, Promise.allSettled waits for all of them and says which ones failed. And sometimes the line is real. The docs call that sequential data fetching: the second request needs a value from the first, like the reviews of whichever tea the shop picked this week, which need that tea's id. No Promise.all can start a request whose input doesn't exist yet. Each row is one way the two reads can wait, with what its recorded terminal printed:

When the line is real, keep the first request quick, cache it if it rarely changes (the Rendering and caching stage teaches "use cache"), and show what you already have while the rest streams in.

Waterfalls between components

Waterfalls also hide between components, where there's no second await to spot. In the next version, MintTea waits for the tea and then returns Reviews, a component that reads the reviews itself. Nothing in MintTea waits for the reviews. Pick both versions:

1import { Suspense } from "react";2import { getReviews, getTea } from "./_data/shop";3 4async function Reviews({ id }: { id: string }) {5  const reviews = await getReviews(id);6  return (7    <ul>8      {reviews.map((review) => (9        <li key={review}>{review}</li>10      ))}11    </ul>12  );13}14 15async function MintTea() {16  const tea = await getTea("mint");17  return (18    <section>19      <h2>20        {tea.name}: ${tea.price}21      </h2>22      <Suspense fallback={<p>Loading reviews…</p>}>23        <Reviews id="mint" />24      </Suspense>25    </section>26  );27}28 29export default function Home() {30  return (31    <main>32      <h1>Tea of the week</h1>33      <Suspense fallback={<p>Loading the tea…</p>}>34        <MintTea />35      </Suspense>36    </main>37  );38}

$ 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 ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ◐ /└ ○ /_not-found ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ Readyquery 1 starts: tea mintquery 1 ends: tea mintquery 2 starts: reviews of mintquery 2 ends: reviews of mint

In the first version, line 16 waits for the tea. Reviews, on line 23, is part of what MintTea returns, so React only meets it once line 16 is done. Its read, on line 5, starts then. The terminal prints the same line-up as two awaits in a row: start, end, start, end. Splitting the code into components didn't make the reads overlap.

In the second version, the page itself returns TeaName and Reviews side by side, each inside its own Suspense, on lines 28 to 33. React renders the page, finds both, and calls both. Each one starts its read, and React doesn't wait for one before calling the next. The terminal prints both starts before either end. Open the Network tab: the first part of the HTML holds both fallbacks, Loading the tea… and Loading reviews…, and each is replaced once its own read has ended. The docs say the same holds for layouts and pages: Next.js renders a layout and its page in parallel, so each one starts loading its data as soon as it can.

Notice line 23 of the first version: <Reviews id="mint" />. The id comes from the page, not from the tea, so the child didn't have to wait. With <Reviews id={tea.id} />, it would: then the child needs the parent's answer, and the waterfall is real.

Starting requests early

Sometimes a component has to wait for one thing before it can decide what to show. The Mint tea reviews page checks that Mint tea is still on the menu, and shows the reviews only if it is. The check has to end before the page decides. Reading the reviews doesn't. Pick each version, in order:

1import { Suspense } from "react";2import { isOnMenu } from "./_data/shop";3import Reviews from "./reviews";4 5async function MintTea() {6  const onMenu = await isOnMenu("mint");7  if (!onMenu) return <p>Not on the menu this week.</p>;8  return <Reviews id="mint" />;9}10 11export default function Home() {12  return (13    <main>14      <h1>Mint tea reviews</h1>15      <Suspense fallback={<p>Loading reviews…</p>}>16        <MintTea />17      </Suspense>18    </main>19  );20}

$ 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 ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ◐ /└ ○ /_not-found ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ Readyquery 1 starts: menu has mintquery 1 ends: menu has mintquery 2 starts: reviews of mintquery 2 ends: reviews of mint

In Check, then read, line 6 waits for isOnMenu("mint"), and line 8 returns Reviews from app/reviews.tsx, which reads the reviews. The terminal shows the menu check end before the reviews' query starts.

In preload, no cache(), app/reviews.tsx gets a small function beside its component, preloadReviews, on lines 3 to 5. It calls getReviews(id) and doesn't wait for it: the void in front of the call says, on purpose, "start this, and ignore what it gives back". Line 6 of the page calls it before the check, so the reviews start first and the check right after, and both run together. But read the terminal to the end: a third query reads the reviews again. When Reviews rendered, line 8 of app/reviews.tsx called getReviews("mint") a second time, and nothing told it that the first call was already on its way.

In preload with cache(), the only change is in app/_data/shop.ts: lines 22 to 24 wrap getReviews in cache(), from React. Now the second call with "mint" gets the promise the first call started. The terminal shows two queries, and both start before either ends. That's the preload pattern from the docs: start the request early without await, call the same function again where the data is used, and make sure that function shares matching calls. The docs suggest keeping the preload function next to the component that uses the data, as here, so you see the two together when you move or delete one.

Preloading has a cost: if the check says no, the reviews were read for nothing. Preload when the check usually says yes, or when the wasted read is cheap. There's also a way with no cache() at all. MintTea can call getReviews("mint") itself before the check, keep the promise, and pass it to Reviews as a prop. A Server Component can await a promise it receives, and there's only one call to share.

One query for many components: React cache()

cache() matters well beyond preloading, because pages read the same data in many places. Here the tea's name and its price are two components, and both call getTea("mint"). The recorder asked for the page twice, as two visits:

1import { Suspense } from "react";2import { getTea } from "./_data/shop";3 4async function TeaName() {5  const tea = await getTea("mint");6  return <h2>{tea.name}</h2>;7}8 9async function TeaPrice() {10  const tea = await getTea("mint");11  return <p>${tea.price} for 100 g</p>;12}13 14export default function Home() {15  return (16    <main>17      <h1>Tea of the week</h1>18      <Suspense fallback={<p>Loading the tea…</p>}>19        <TeaName />20        <TeaPrice />21      </Suspense>22    </main>23  );24}

$ 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 ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ◐ /└ ○ /_not-found ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content $ next start▲ Next.js 16.4.3- Local:         http://127.0.0.1:3000- Network:       http://127.0.0.1:3000✓ Readyquery 1 starts: tea mintquery 2 starts: tea mintquery 1 ends: tea mintquery 2 ends: tea mintquery 3 starts: tea mintquery 4 starts: tea mintquery 3 ends: tea mintquery 4 ends: tea mint

Without cache(), the terminal shows queries 1 and 2 for the first visit, both reading the same tea, then queries 3 and 4 for the second. With it, lines 18 to 20 of app/_data/shop.ts read export const getTea = cache((id: string) => { … }). cache takes a function and gives back a new one that remembers its results. The first call with "mint" runs the query and keeps the promise it returns. Every later call with "mint" during the same request gets that same promise, so both components wait for one query. The terminal shows one query per visit: query 1 for the first, query 2 for the second.

The second visit ran a query of its own. react.dev says why: for each new server request, React forgets what every cache() function remembered. One visitor never gets another visitor's answer from it. A few more rules, from react.dev:

• Make it once, at the top of a module, and import it everywhere. Calling cache() inside a component makes a new function on every render.
• Pass values that compare equal. React compares each argument with Object.is: the same string or number matches, but two objects with the same contents are still two objects. Pass the id, not an object built on the spot.
• It works in Server Components. Called outside a component's render, the function runs every time.
• It remembers errors too. If the function throws for an argument, later calls with that argument get the same error, until the request ends.

Don't confuse React's cache() with Next.js's "use cache". Each row is one thing that keeps a result, and for how long:

Request memoization for fetch

fetch gets this without cache(). Here, InStock and StockList both call getStock, which fetches the supplier's stock list. The supplier is a stand-in server that the recorder started on this computer: it answers GET /stock with three teas, and it keeps a list of every request it receives. Its address reaches the app in the environment variable SUPPLIER_API_URL.

1import { Suspense } from "react";2 3type Stock = { id: string; name: string; stock: number };4 5async function getStock() {6  const response = await fetch(`${process.env.SUPPLIER_API_URL}/stock`);7  return (await response.json()) as Stock[];8}9 10async function InStock() {11  const teas = await getStock();12  const count = teas.filter((tea) => tea.stock > 0).length;13  return <p>{count} teas in stock today</p>;14}15 16async function StockList() {17  const teas = await getStock();18  return (19    <ul>20      {teas.map((tea) => (21        <li key={tea.id}>22          {tea.name}: {tea.stock > 0 ? `${tea.stock} left` : "Sold out"}23        </li>24      ))}25    </ul>26  );27}28 29export default function Home() {30  return (31    <main>32      <h1>Tea shop</h1>33      <Suspense fallback={<p>Asking the supplier…</p>}>34        <InStock />35        <StockList />36      </Suspense>37    </main>38  );39}

Each row is one version, with the requests the stand-in supplier recorded for the same two visits:

Both versions show the same page: 2 teas in stock today and the three teas. With the plain fetch, the supplier received 2 requests for 2 visits: one per visit, though two components fetched. Next.js remembers a fetch with GET, the same address and the same options while it renders one request, and gives the second caller the first one's answer. The docs call this memoization, and older docs called it request memoization. In the second version, line 6 makes an AbortController and line 7 passes its signal to fetch. A signal means the caller controls the request, so Next.js leaves it alone, and the supplier received 4: two per visit. The docs give this as the way to opt out.

The rules, from the docs:

• It only applies to GET requests, with the same address and the same options.
• It lasts one render pass. The next request fetches again, as the second visit did.
• It works in layouts, pages and other Server Components, and in functions like generateMetadata. It doesn't in Route Handlers, which aren't part of the React tree.
• For anything that isn't fetch, like a database query, use React's cache().

Planning the tea page's requests

Planning a page's requests comes down to one question for each pair of reads: does the second one need the first one's answer? If not, they can start together. Then:

• Inside one component, call every function before the first await, and wait for them with Promise.all.
• Between components, let siblings read their own data. Don't return a component that reads after an await it doesn't need.
• When a component must wait anyway, start what doesn't depend on the wait first: preload it, or pass the promise down.
• When many components read the same data, wrap your own data functions in cache(). A GET fetch is shared for you.

Sort these pairs of reads: which can start together, and which must wait in line?

Common mix-ups

• "async code runs its requests at the same time." No. Each await pauses the function. Two in a row made query 2 start after query 1 ended.
• "Promise.all makes each request faster." No. Each query waited just as long. They overlapped instead of following each other.
• "Splitting a page into components removes waterfalls." No. A child returned after its parent's await started its read late. Siblings started together.
• "cache() keeps data for the next visitor." No. React forgets it at the end of each request. The second visit printed a query of its own.
• "Next.js caches every fetch." Not since Next.js 15. Memoization shares a GET within one render; the second visit asked the supplier again.
• "Every waterfall is a mistake." No. When the second request needs the first one's answer, the order is real. Make the first one quick, or cache it.

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: each query prints when it starts and ends, and waits the same time.

import { Suspense } from "react";
import { getReviews, getTea } from "./_data/shop";

async function MintTea() {
  const tea = await getTea("mint");
  const reviews = await getReviews("mint");
  return (
    <section>
      <h2>
        {tea.name}: ${tea.price}
      </h2>
      <ul>
        {reviews.map((review) => (
          <li key={review}>{review}</li>
        ))}
      </ul>
    </section>
  );
}

export default function Home() {
  return (
    <main>
      <h1>Tea of the week</h1>
      <Suspense fallback={<p>Loading the tea…</p>}>
        <MintTea />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, getTea } from "./_data/shop";

async function MintTea() {
  const teaPromise = getTea("mint");
  const reviewsPromise = getReviews("mint");
  const tea = await teaPromise;
  const reviews = await reviewsPromise;
  return (
    <section>
      <h2>
        {tea.name}: ${tea.price}
      </h2>
      <ul>
        {reviews.map((review) => (
          <li key={review}>{review}</li>
        ))}
      </ul>
    </section>
  );
}

export default function Home() {
  return (
    <main>
      <h1>Tea of the week</h1>
      <Suspense fallback={<p>Loading the tea…</p>}>
        <MintTea />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, getTea } from "./_data/shop";

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

async function MintTea() {
  const tea = await getTea("mint");
  return (
    <section>
      <h2>
        {tea.name}: ${tea.price}
      </h2>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <Reviews id="mint" />
      </Suspense>
    </section>
  );
}

export default function Home() {
  return (
    <main>
      <h1>Tea of the week</h1>
      <Suspense fallback={<p>Loading the tea…</p>}>
        <MintTea />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, getTea } from "./_data/shop";

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

async function TeaName({ id }: { id: string }) {
  const tea = await getTea(id);
  return (
    <h2>
      {tea.name}: ${tea.price}
    </h2>
  );
}

export default function Home() {
  return (
    <main>
      <h1>Tea of the week</h1>
      <Suspense fallback={<p>Loading the tea…</p>}>
        <TeaName id="mint" />
      </Suspense>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <Reviews id="mint" />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, getTea } from "./_data/shop";

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

async function MintTea() {
  const tea = await getTea("mint");
  return (
    <section>
      <h2>
        {tea.name}: ${tea.price}
      </h2>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <Reviews id={tea.id} />
      </Suspense>
    </section>
  );
}

export default function Home() {
  return (
    <main>
      <h1>Tea of the week</h1>
      <Suspense fallback={<p>Loading the tea…</p>}>
        <MintTea />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { isOnMenu } from "./_data/shop";
import Reviews from "./reviews";

async function MintTea() {
  const onMenu = await isOnMenu("mint");
  if (!onMenu) return <p>Not on the menu this week.</p>;
  return <Reviews id="mint" />;
}

export default function Home() {
  return (
    <main>
      <h1>Mint tea reviews</h1>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <MintTea />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getReviews, isOnMenu } from "./_data/shop";
import Reviews from "./reviews";

async function MintTea() {
  const reviews = getReviews("mint");
  const onMenu = await isOnMenu("mint");
  if (!onMenu) return <p>Not on the menu this week.</p>;
  return <Reviews reviews={reviews} />;
}

export default function Home() {
  return (
    <main>
      <h1>Mint tea reviews</h1>
      <Suspense fallback={<p>Loading reviews…</p>}>
        <MintTea />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getTea } from "./_data/shop";

async function TeaName() {
  const tea = await getTea({ id: "mint" });
  return <h2>{tea.name}</h2>;
}

async function TeaPrice() {
  const tea = await getTea({ id: "mint" });
  return <p>${tea.price} for 100 g</p>;
}

export default function Home() {
  return (
    <main>
      <h1>Tea of the week</h1>
      <Suspense fallback={<p>Loading the tea…</p>}>
        <TeaName />
        <TeaPrice />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getTea } from "./_data/shop";

async function TeaName() {
  const tea = await getTea("mint");
  return <h2>{tea.name}</h2>;
}

async function TeaPrice() {
  const tea = await getTea("mint");
  return <p>${tea.price} for 100 g</p>;
}

export default function Home() {
  return (
    <main>
      <h1>Tea of the week</h1>
      <Suspense fallback={<p>Loading the tea…</p>}>
        <TeaName />
        <TeaPrice />
      </Suspense>
    </main>
  );
}

Check your understanding

Key takeaways

• A waterfall is requests that run one after another. Each link adds its wait before the content behind it can show.
• A request starts when its function is called. Call every independent read before the first await, and wait with Promise.all.
• A child returned after its parent's await starts late. Siblings start together, and the docs say a layout and its page do too.
• When a component must wait first, preload what doesn't depend on the wait, or pass its promise down.
• React's cache() shares one call per argument for the rest of a request. A GET fetch is memoized the same way by Next.js. Neither keeps anything for the next visit; "use cache" does.
• When the second request needs the first one's answer, the order is real. Make the first one quick, or cache it.

Coming next: Streaming with Suspense. It follows the page's HTML as it arrives in pieces, and shows where to put each Suspense.