Data Fetching

import "server-only";

// Stand-in for an ORM client (Prisma, Drizzle…): same shape, rows in memory, a real wait.
const stock = [
  { sku: "p1", warehouse: "YUL-EAST-7", qty: 12 },
  { sku: "p2", warehouse: "YYZ-NORTH-2", qty: 0 },
];

export const db = {
  stock: {
    async findMany() {
      // A real client would connect with process.env.DB_PASSWORD here.
      console.log("[db] SELECT sku, warehouse, qty FROM stock");
      await new Promise((resolve) => setTimeout(resolve, 200));
      return stock;
    },
  },
};

import { Suspense } from "react";
import { db } from "@/lib/db";

async function StockTable() {
  const rows = await db.stock.findMany();
  return (
    <table>
      <tbody>
        {rows.map((r) => (
          <tr key={r.sku}>
            <td>{r.sku}</td>
            <td>{r.qty > 0 ? `${r.qty} in stock` : "Sold out"}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

export default function StockPage() {
  return (
    <main>
      <h1>Stock</h1>
      <Suspense fallback={<p>Checking stock…</p>}>
        <StockTable />
      </Suspense>
    </main>
  );
}

import { ProductList } from "./product-list";

export default function ProductsPage() {
  return (
    <main>
      <h1>Products</h1>
      <ProductList />
    </main>
  );
}

Error: Route "/products": 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>)
…
Export encountered an error on /products/page: /products, exiting the build.

// A fake API for this chapter's examples: every route waits on purpose and logs each hit.
import { createServer } from "node:http";

const routes = {
  "/products": [300, [{ id: "p1", name: "Desk lamp", price: 39 }, { id: "p2", name: "Notebook", price: 6 }]],
  "/artists/nina": [300, { id: "a1", name: "Nina Simone" }],
  "/artists/nina/albums": [500, [{ id: "al1", title: "Pastel Blues" }, { id: "al2", title: "Wild Is the Wind" }]],
  "/artists/nina/shows": [400, [{ id: "s1", city: "Montreux" }]],
  "/me": [300, { id: "u1", name: "Rohit", plan: "pro" }],
};
const hits = {};
let epoch = 0;
let last = 0;

createServer(async (req, res) => {
  const { pathname } = new URL(req.url, "http://localhost");
  if (pathname === "/hits") return res.end(JSON.stringify(hits));
  const now = Date.now();
  if (now - last > 1000) epoch = now; // a quiet second starts a new "page load"
  last = now;
  hits[pathname] = (hits[pathname] ?? 0) + 1;
  console.log(`+${String(now - epoch).padStart(4)}ms ${req.method} ${pathname} (hit ${hits[pathname]})`);
  const [ms, body] = routes[pathname] ?? [0, { error: "not found" }];
  await new Promise((r) => setTimeout(r, ms));
  res.writeHead(routes[pathname] ? 200 : 404, { "content-type": "application/json", connection: "close" });
  res.end(JSON.stringify(body));
}).listen(4704, () => console.log("fake API on http://localhost:4704"));

// node observe.mjs <url> [text…]: prints when each chunk of the response arrived and which texts it contained.
const [url, ...marks] = process.argv.slice(2);
const start = performance.now();
const res = await fetch(url, { headers: { "accept-encoding": "identity" } });
console.log(`status ${res.status} after ${Math.round(performance.now() - start)}ms`);
const reader = res.body.getReader();
const decoder = new TextDecoder();
let i = 0;
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value, { stream: true });
  const found = marks.filter((m) => text.includes(m));
  console.log(`chunk ${i++} +${String(Math.round(performance.now() - start)).padStart(4)}ms ${String(value.length).padStart(6)} bytes ${found.join(", ")}`);
}
console.log(`done after ${Math.round(performance.now() - start)}ms`);

import { Suspense } from "react";
import { getAlbums, getArtist } from "@/lib/api";

async function Albums() {
  const albums = await getAlbums("nina");
  return <ul>{albums.map((a) => <li key={a.id}>{a.title}</li>)}</ul>;
}

async function ArtistHeader() {
  const artist = await getArtist("nina");
  // <Albums> only exists once this component has returned, so its fetch starts late.
  return (
    <section>
      <h2>{artist.name}</h2>
      <Albums />
    </section>
  );
}

export default function Page() {
  return (
    <Suspense fallback={<p>Loading artist…</p>}>
      <ArtistHeader />
    </Suspense>
  );
}

import { Suspense } from "react";
import { getAlbums, getArtist, getShows } from "@/lib/api";

async function Name() {
  const artist = await getArtist("nina");
  return <h2>{artist.name}</h2>;
}

async function Albums() {
  const albums = await getAlbums("nina");
  return <ul>{albums.map((a) => <li key={a.id}>{a.title}</li>)}</ul>;
}

async function Shows() {
  const shows = await getShows("nina");
  return <p>Next show: {shows[0]?.city}</p>;
}

export default function Page() {
  return (
    <main>
      <Suspense fallback={<h2>…</h2>}>
        <Name />
      </Suspense>
      <Suspense fallback={<p>Loading albums…</p>}>
        <Albums />
      </Suspense>
      <Suspense fallback={<p>Loading shows…</p>}>
        <Shows />
      </Suspense>
    </main>
  );
}

$ node observe.mjs http://localhost:4504/nested …
chunk 8 + 326ms    148 bytes Nina Simone
chunk 11 + 829ms   1170 bytes Pastel Blues
done after 833ms
-- API log
+   0ms GET /artists/nina (hit 10)
+ 301ms GET /artists/nina/albums (hit 15)

$ node observe.mjs http://localhost:4504/siblings …
chunk 8 + 328ms     97 bytes Nina Simone
chunk 11 + 430ms     94 bytes Montreux
chunk 13 + 528ms    115 bytes Pastel Blues
done after 532ms
-- API log
+   0ms GET /artists/nina (hit 11)
+   1ms GET /artists/nina/albums (hit 16)
+   1ms GET /artists/nina/shows (hit 6)

import { getAlbums } from "@/lib/api";

// Starts the request without waiting for it. The promise is dropped on purpose:
// the identical fetch inside <Albums> picks up the same in-flight request.
export const preloadAlbums = (name: string) => {
  void getAlbums(name);
};

export async function Albums({ name }: { name: string }) {
  const albums = await getAlbums(name);
  return <ul>{albums.map((a) => <li key={a.id}>{a.title}</li>)}</ul>;
}

import { Suspense } from "react";
import { getMe } from "@/lib/api";
import { Albums } from "@/components/albums";

async function MemberAlbums() {
  const me = await getMe(); // 300 ms: only "pro" members see albums
  if (me.plan !== "pro") return <p>Upgrade to see albums.</p>;
  return <Albums name="nina" />; // its 500 ms fetch starts only now
}

export default function Page() {
  return (
    <Suspense fallback={<p>Loading albums…</p>}>
      <MemberAlbums />
    </Suspense>
  );
}

import { Suspense } from "react";
import { getMe } from "@/lib/api";
import { Albums, preloadAlbums } from "@/components/albums";

async function MemberAlbums() {
  preloadAlbums("nina"); // start the 500 ms fetch now…
  const me = await getMe(); // …while this 300 ms check runs
  if (me.plan !== "pro") return <p>Upgrade to see albums.</p>;
  return <Albums name="nina" />; // same URL and options: reuses the request above
}

export default function Page() {
  return (
    <Suspense fallback={<p>Loading albums…</p>}>
      <MemberAlbums />
    </Suspense>
  );
}

$ node observe.mjs http://localhost:4504/gated …
chunk 8 + 831ms    197 bytes Pastel Blues
done after 835ms
-- API log
+   0ms GET /me (hit 6)
+ 303ms GET /artists/nina/albums (hit 17)

$ node observe.mjs http://localhost:4504/preload …
chunk 8 + 525ms    197 bytes Pastel Blues
done after 530ms
-- API log
+   0ms GET /artists/nina/albums (hit 18)
+   0ms GET /me (hit 7)

Route (app)
┌ ○ /_not-found
├ ◐ /gated
├ ◐ /nested
├ ◐ /parallel
├ ◐ /preload
├ ◐ /sequential
└ ◐ /siblings


○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

import { getOrders, getRecommendations, getRevenue } from "@/lib/db";

// The same three reads, awaited together at the top of the page.
export default async function Report() {
  const [revenue, orders, items] = await Promise.all([getRevenue(), getOrders(), getRecommendations()]);
  return (
    <main>
      <h1>Report</h1>
      <p>Revenue today: ${revenue.today}</p>
      <p>{orders.length} recent orders</p>
      <p>Recommended: {items.join(", ")}</p>
    </main>
  );
}

export default function Loading() {
  return <p>Loading report…</p>;
}

$ node observe.mjs http://localhost:4504/report "Loading report" "Revenue today" "Recommended:"
status 200 after 47ms
chunk 0 +  48ms   1569 bytes Loading report
chunk 9 +2049ms    342 bytes Revenue today, Recommended:
done after 2050ms

import { Suspense } from "react";
import { notFound } from "next/navigation";
import { getOrders } from "@/lib/db";

async function OrderDetails() {
  const orders = await getOrders();
  const order = orders.find((o) => o.id === "o-9999");
  if (!order) notFound(); // runs after streaming has started
  return <p>Order {order.id}</p>;
}

export default function OrderPage() {
  return (
    <main>
      <h1>Order</h1>
      <Suspense fallback={<p>Loading order…</p>}>
        <OrderDetails />
      </Suspense>
    </main>
  );
}

$ node observe.mjs http://localhost:4504/order "Loading order" "noindex"
status 200 after 42ms
chunk 0 +  42ms   1538 bytes Loading order
chunk 10 +1044ms    112 bytes noindex
done after 1045ms

headless Chrome after load:
{ "text": "404\nThis page could not be found.",
  "title": "404: This page could not be found.",
  "robots": "noindex" }

Route (app)
┌ ○ /_not-found
├ ◐ /dashboard
├ ◐ /order
└ ◐ /report


○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

let queries = 0;

// Stand-in for an ORM query: it logs every time it really runs.
export async function getOrders(userId: string) {
  console.log(`[db] query #${++queries}: SELECT * FROM orders WHERE user_id = '${userId}'`);
  await new Promise((resolve) => setTimeout(resolve, 200));
  return [{ id: "o-1007", total: 64 }, { id: "o-1006", total: 18 }];
}

export async function getOrdersFor(user: { id: string }) {
  return getOrders(user.id);
}

import { cache } from "react";
import { getOrders, getOrdersFor } from "./db";

// One shared, module-level wrapper: every component that imports it shares its per-request memo.
export const getOrdersCached = cache(getOrders);

// Object argument: cache() compares arguments with Object.is, so a fresh object never matches.
export const getOrdersForCached = cache(getOrdersFor);

import { Suspense } from "react";
import { getOrders } from "@/lib/db";
import { getOrdersCached, getOrdersForCached } from "@/lib/orders";

async function Plain() {
  const a = await getOrders("u1");
  const b = await getOrders("u1");
  return <p>Plain: {a.length + b.length} rows</p>;
}

async function Cached() {
  const a = await getOrdersCached("u1");
  const b = await getOrdersCached("u1");
  return <p>cache(): {a.length + b.length} rows</p>;
}

async function CachedObjectArg() {
  const a = await getOrdersForCached({ id: "u1" });
  const b = await getOrdersForCached({ id: "u1" });
  return <p>cache() with objects: {a.length + b.length} rows</p>;
}

export default function OrdersPage({ searchParams }: PageProps<"/orders">) {
  return (
    <Suspense fallback={<p>Loading orders…</p>}>
      {searchParams.then(({ mode }) =>
        mode === "plain" ? <Plain /> : mode === "object" ? <CachedObjectArg /> : <Cached />,
      )}
    </Suspense>
  );
}

next start terminal, one request each:

== /orders?mode=plain
[db] query #1: SELECT * FROM orders WHERE user_id = 'u1'
[db] query #2: SELECT * FROM orders WHERE user_id = 'u1'
[db] query #3: SELECT * FROM orders WHERE user_id = 'u1'
[db] query #4: SELECT * FROM orders WHERE user_id = 'u1'
== /orders
[db] query #5: SELECT * FROM orders WHERE user_id = 'u1'
[db] query #6: SELECT * FROM orders WHERE user_id = 'u1'
== /orders?mode=object
[db] query #7: SELECT * FROM orders WHERE user_id = 'u1'
[db] query #8: SELECT * FROM orders WHERE user_id = 'u1'
[db] query #9: SELECT * FROM orders WHERE user_id = 'u1'
[db] query #10: SELECT * FROM orders WHERE user_id = 'u1'

[db] t=2275 query #1: SELECT * FROM orders WHERE user_id = 'u1'
[db] t=2290 query #2: SELECT * FROM orders WHERE user_id = 'u1'
[db] t=2477 query #1 resolved
[db] t=2477 query #3: SELECT * FROM orders WHERE user_id = 'u1'
[db] t=2492 query #2 resolved
[db] t=2492 query #4: SELECT * FROM orders WHERE user_id = 'u1'
[db] t=2678 query #3 resolved
[db] t=2693 query #4 resolved

== /account      +   0ms GET /me (hit 14)
== /opt-out      +   0ms GET /me (hit 15)
                 +   0ms GET /me (hit 16)
== /orders?mode=plain   [db] query #1 … [db] query #2
== /orders              [db] query #3
== /orders?mode=object  [db] query #4 … [db] query #5

import { getMe } from "@/lib/api";

// Route Handlers are not rendered by React, so nothing memoizes these two calls.
export async function GET() {
  const first = await getMe();
  const second = await getMe();
  return Response.json({ same: first.id === second.id });
}

$ curl -s http://localhost:4504/api/me
{"same":true}
-- API log
+   0ms GET /me (hit 12)
+ 302ms GET /me (hit 13)

Route (app)
┌ ○ /_not-found
├ ◐ /account
├ ƒ /api/me
├ ◐ /opt-out
└ ◐ /orders


○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content
ƒ  (Dynamic)            server-rendered on demand

"use client";

import { use, useState } from "react";

type Notification = { id: number; text: string };

export function InboxList({ itemsPromise }: { itemsPromise: Promise<Notification[]> }) {
  const items = use(itemsPromise); // suspends until the server's promise resolves
  const [read, setRead] = useState<number[]>([]);
  return (
    <ul>
      {items.map((n) => (
        <li key={n.id} onClick={() => setRead([...read, n.id])}>
          {read.includes(n.id) ? "✓ " : ""}
          {n.text}
        </li>
      ))}
    </ul>
  );
}

import { Suspense } from "react";
import { connection } from "next/server";
import { InboxList } from "@/components/inbox-list";
import { getNotifications } from "@/lib/notifications";

async function loadInbox() {
  await connection(); // request-time data, not part of the prerendered shell
  return getNotifications("promise prop");
}

export default function Page() {
  const itemsPromise = loadInbox(); // started here, not awaited
  return (
    <main>
      <h1>Inbox</h1>
      <Suspense fallback={<p>Loading notifications…</p>}>
        <InboxList itemsPromise={itemsPromise} />
      </Suspense>
    </main>
  );
}

headless Chrome, 11.5 s after loading /promise, then clicking the first item:
{ "fetches": [], "clicked": "✓ Your order o-1007 shipped" }
next start terminal:
[db] read #11 from promise prop

import { Suspense } from "react";
import { SWRConfig } from "swr";
import { getProduct } from "./data"; // server-side function
import { ProductView } from "./product-view";

export default function Page({ params }: PageProps<"/products/[id]">) {
  return (
    <Suspense fallback={<p>Loading…</p>}>
      {params.then(({ id }) => (
        // Not awaited: only components that read this key suspend
        <SWRConfig value={{ fallback: { [`/api/products/${id}`]: getProduct(id) } }}>
          <ProductView id={id} />
        </SWRConfig>
      ))}
    </Suspense>
  );
}

"use client";

import useSWR from "swr";

const fetcher = (url: string) => fetch(url).then((r) => r.json());

export function ProductView({ id }: { id: string }) {
  // Same key as the server fallback: first render uses the server's data, then SWR keeps it fresh.
  const { data } = useSWR(`/api/products/${id}`, fetcher, { suspense: true, refreshInterval: 10_000 });
  return <h1>{data.name}</h1>;
}

"use client";

import { createContext, use } from "react";

type User = { id: string; name: string; plan: "pro" };

const UserContext = createContext<Promise<User> | null>(null);

export function UserProvider({ userPromise, children }: { userPromise: Promise<User>; children: React.ReactNode }) {
  return <UserContext value={userPromise}>{children}</UserContext>;
}

export function useUser() {
  const promise = use(UserContext);
  if (!promise) throw new Error("useUser must be used inside <UserProvider>");
  return use(promise);
}

"use client";

import { useUser } from "./user-context";

export function PlanBadge() {
  const user = useUser();
  return <strong>{user.plan.toUpperCase()}</strong>;
}

import { Suspense } from "react";
import { UserProvider } from "@/components/user-context";
import { PlanBadge } from "@/components/plan-badge";
import { getCurrentUser } from "@/lib/user";

export default function StudioLayout({ children }: LayoutProps<"/studio">) {
  const userPromise = getCurrentUser(); // started once, not awaited
  return (
    <UserProvider userPromise={userPromise}>
      <header>
        <Suspense fallback={<strong>…</strong>}>
          <PlanBadge />
        </Suspense>
      </header>
      {children}
    </UserProvider>
  );
}

import { Suspense } from "react";
import { PlanBadge } from "@/components/plan-badge";

export default function StudioPage() {
  return (
    <main>
      <h1>Studio</h1>
      <Suspense fallback={<p>…</p>}>
        <p>
          Exports on your plan: <PlanBadge />
        </p>
      </Suspense>
    </main>
  );
}

Route (app)
┌ ○ /_not-found
├ ◐ /shop
└ ◐ /studio


○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

./src/lib/dal.ts:1:1
Error: 'server-only' cannot be imported from a Client Component module
> 1 | import "server-only";
    | ^^^^^^^^^^^^^^^^^^^^^

It should only be used from a Server Component.

Import traces:
  Client Component Browser:
    ./src/lib/dal.ts [Client Component Browser]
    ./src/components/team-count.tsx [Client Component Browser]
    ./src/components/team-count.tsx [Server Component]
    ./src/app/count/page.tsx [Server Component]

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
  experimental: {
    taint: true, // enables React's taint APIs (and React's experimental channel for app/)
  },
};

export default nextConfig;

/// <reference types="react/experimental" />
import "server-only";
import { experimental_taintObjectReference, experimental_taintUniqueValue } from "react";

type UserRow = { id: string; name: string; email: string; passwordHash: string };

const users: UserRow[] = [
  { id: "u1", name: "Rohit", email: "rohit@example.com", passwordHash: "$argon2id$v=19$m=65536$c2FsdA$aGFzaA" },
];

export async function listUsers() {
  await new Promise((resolve) => setTimeout(resolve, 50));
  for (const row of users) {
    experimental_taintObjectReference("Don't pass a whole user row to the client; map it to a DTO.", row);
    experimental_taintUniqueValue("Password hashes never leave the server.", row, row.passwordHash);
  }
  return users;
}

"use client";

export function MemberCard({ member }: { member: { name: string } }) {
  return <li>{member.name}</li>;
}

"use client";

export function HashBadge({ value }: { value: string }) {
  return <code>{value.slice(0, 8)}</code>;
}

import { Suspense } from "react";
import { connection } from "next/server";
import { MemberCard } from "@/components/member-card";
import { listUsers } from "@/lib/db";

async function Team() {
  await connection();
  const rows = await listUsers();
  return <ul>{rows.map((row) => <MemberCard key={row.id} member={row} />)}</ul>;
}

export default function Page() {
  return (
    <Suspense fallback={<p>Loading team…</p>}>
      <Team />
    </Suspense>
  );
}