The 'use cache' directive

One tea, fetched once

Cache Components showed the model: work that waits is fresh for each request, unless you cache it. "use cache" is how you cache it. It's a directive, a string at the top of a function or a file, and it tells Next.js: keep what this returns, and give the same inputs the same stored copy. Here, the tea shop's Teas page shows one tea, picked by the address, like /teas?tea=mint. It's a real Next.js 16.4.3 project, built with next build and run with next start, and the result is a recording.

1const api = process.env.SUPPLIER_API_URL;2 3export type Tea = { id: string; name: string; price: number };4 5export async function getTea(id: string): Promise<Tea> {6  "use cache";7  const response = await fetch(`${api}/teas/${id}`);8  return response.json();9}

In lib/supplier.ts, the file shown first, getTea on lines 5 to 9 asks the tea supplier's API for one tea. Line 6, "use cache", is the whole change: it caches the function. Open app/teas/page.tsx. TeaDetails, on lines 4 to 12, reads tea from the address on line 5, and line 6 calls getTea with it. The address is only known when a request comes in, so lines 18 to 20 put TeaDetails in Suspense.

The supplier is a stand-in that ran on the same computer and kept every request it got. Three visits came in: ?tea=mint, ?tea=mint again, and ?tea=green. Pick each one above the page in the Browser tab. The supplier was asked for /teas/mint once and /teas/green once. The second mint visit got the copy the first one stored. Nothing was asked during the build, because the build didn't know which tea anyone would pick.

Files, components and functions

The directive goes at the very top of a function's body, or at the very top of a file. That gives three places:

• A function, like getTea: its result, usually data, is stored.
• A component, which is a function too: its props are its arguments, and what it renders is its result.
• A file: every function the file exports is cached, as if each one started with the directive.

In all three, the function must be async, or the build stops. Each button below is the same shop with the directive in a different place, visited by the same three visitors. Before you click, guess how many times each version asks for mint.

1const api = process.env.SUPPLIER_API_URL;2 3export type Tea = { id: string; name: string; price: number };4 5export async function getTea(id: string): Promise<Tea> {6  const response = await fetch(`${api}/teas/${id}`);7  return response.json();8}

The three places that build all store a copy for each tea: the supplier was asked once for mint and once for green. Without the directive, it was asked for mint twice. A file-level directive turns every exported function into a cached one, so a small helper like teaUrl, which isn't async, stops the build. Move such a helper to a file of its own, or don't export it.

A page.tsx or layout.tsx file can start with the directive too. Next.js's docs say each one is then cached on its own, and a cached layout's children pass through: they're not cached with the layout.

Arguments and closures become the key

A cache key is the label a stored copy is filed under. When a cached function is called, Next.js builds the key from the call and looks for a copy with that key. If there is one, the function's body doesn't run. Each row is one part of the key in Next.js 16.4.3:

In Next.js's own code, the key is one line, in use-cache-wrapper.ts:

const cacheKeyParts: CacheKeyParts = [id, args, implementationPart]

const encodeCacheKeyParts = () =>
  encodeReply(cacheKeyParts, {
    temporaryReferences,
    signal: hangingInputAbortSignal,
  })

id is the function's ID, and args its arguments, captured values included. implementationPart is, by default, the build's ID in a production build (lines 3917 to 3931), with an extra part in next dev that changes when you edit a Server Component. Next.js turns the three into one string with React's encodeReply, the same encoding a Server Action's arguments use (lines 2291 to 2297). That's why the same values are allowed in both. temporaryReferences is where values that can only pass through, like JSX, are set aside instead of going into the key.

Values from outside the function

A function can use variables from the code around it: that's a closure. A cached closure's key includes the values it uses, as if they were arguments. Here getDetails is defined inside TeaDetails and takes no arguments at all:

1import { Suspense } from "react";2 3const api = process.env.SUPPLIER_API_URL;4 5async function TeaDetails({ searchParams }: Pick<PageProps<"/teas">, "searchParams">) {6  const { tea = "green" } = await searchParams;7 8  async function getDetails() {9    "use cache";10    const response = await fetch(`${api}/teas/${tea}`);11    return response.json();12  }13 14  const details = await getDetails();15  return (16    <p>17      {details.name}: ${details.price}18    </p>19  );20}21 22export default function TeasPage({ searchParams }: PageProps<"/teas">) {23  return (24    <main>25      <h1>Our teas</h1>26      <Suspense fallback={<p>Finding the tea…</p>}>27        <TeaDetails searchParams={searchParams} />28      </Suspense>29    </main>30  );31}

Line 6 reads tea from the address. getDetails, on lines 8 to 12, is cached on line 9, and line 10 uses tea in the supplier's address. The same three visits asked for mint once and green once, and the green visit showed Green tea: $4. If tea weren't in the key, the green visit would have received the mint copy. Next.js passes captured values in as hidden arguments, so they follow the same rules as arguments.

Where the copies are kept

During next build, a cached result that a page needs goes into that page's prerendered output. While next start runs, copies made for requests are kept in the server's memory: by default, a store that drops the least recently used copies when it passes 50 MB, the cacheMaxMemorySize option. The build's own memory is gone by then: it isn't carried into next start as it was. This version shows a tea of the day on the home page, with getTea("mint"):

1import { getTea } from "@/lib/supplier";2 3export default async function Home() {4  const tea = await getTea("mint");5  return (6    <main>7      <h1>Tea shop</h1>8      <p>Tea of the day: {tea.name}</p>9    </main>10  );11}

$ 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 (4/4)  Finalizing page optimization ... Route (app)      Revalidate  Expire┌ ○ /                   15m      1y├ ○ /_not-found└ ◐ /teas ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

The build asked for mint once, for the home page, and printed ○ / 15m 1y. The home page itself is served from what the build prerendered, with the tea already in it. Then a visit to another route, /teas?tea=mint, asked for mint again: nothing that route kept from the build held that copy.

A route can keep cached results of its own, though. When the build prerenders a ◐ route, it saves the route's postponed state, what Next.js needs to finish the page for a request, and with it the cached results the build filled for that route (Next.js calls them the resume data cache; postponed-state.ts). When that same route is finished for a visit, a cached call looks there first (use-cache-wrapper.ts, line 2470), so it can reuse what its own build filled. A new build has a new ID, so no copy survives a deploy, and an app on several servers has a memory store on each. Private and remote caches shows a store all servers share.

15m comes from the default lifetime, which applies when a cached function doesn't call cacheLife. The docs give its three times:

• stale, 5 minutes: how long the browser may reuse a copy without asking the server.
• revalidate, 15 minutes: after this, the server should make a new copy.
• No expire: no time after which an old copy must stop being used.

What happens at the revalidate time depends on where the copy is kept. In Next.js 16.4.3, the default in-memory store in next start drops a copy once it's past its revalidate time (default.ts, lines 104 to 125), so the next call after 15 minutes runs the function again. That's this version's store, not a rule of cacheLife. 1y is Next.js's expireTime option, a year, which the build uses when nothing set a limit. The docs recommend calling cacheLife in every cached function, so its lifetime is written where you can see it; Cache lifetimes and tags teaches it.

What can go in and come out

Everything in the key has to be turned into text, and the result has to be stored and sent again later. So a cached function's inputs and output must be serializable: values that can be written down and read back as the same values. The docs give the rules: arguments follow React's rules for a Server Action's arguments, and the result follows React's rules for props passed to a Client Component (Composing Server and Client Components). Each row is one kind of value:

1const api = process.env.SUPPLIER_API_URL;2 3export type Tea = { id: string; name: string; price: number };4 5export async function getTea(id: string): Promise<Tea> {6  "use cache";7  const response = await fetch(`${api}/teas/${id}`);8  return response.json();9}

$ 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 (4/4)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found└ ◐ /teas ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

All three mistakes built: ◐ /teas. The cached call sits inside a part that waits for the request, so the build never ran it, and the error came on the first visit. The page's HTML kept Finding the tea… and the tea never arrived; the server printed the error, which the Terminal tab shows after the build. Each message, as next start printed it, names the problem:

• A class instance in: Cannot access value on the server. You cannot dot into a temporary client reference from a server component. You can only pass the value through to the client. The TeaId arrived as a reference that can only be passed through, so reading id.value failed before the supplier was asked.
• A function in: Attempted to call a temporary Client Reference from the server but it is on the client. It's not possible to invoke a client function from the server, it can only be rendered as a Component or passed to props of a Client Component. The supplier answered, then calling format failed.
• A class instance out: Only plain objects, and a few built-ins, can be passed to Client Components from Server Components. Classes or null prototypes are not supported. The supplier answered, then storing the Tea failed.

The fix is the same each time: pass and return plain values. getTea(id: string) takes the tea's id, not an object around it, and returns the JSON as it came.

Request data stays outside

A stored copy is shared by every request with the same key, so it can't depend on one request. Reading request data inside a cached function is an error:

1import { cookies } from "next/headers";2 3const api = process.env.SUPPLIER_API_URL;4 5export async function getFavorite() {6  "use cache";7  const id = (await cookies()).get("favorite")?.value ?? "green";8  const response = await fetch(`${api}/teas/${id}`);9  return response.json();10}

$ 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": `cookies()` can't be read inside `"use cache"`. Read it outside the cached function and pass what you need as an argument.Learn more: https://nextjs.org/docs/messages/next-request-in-use-cache    at g (lib/supplier.ts:7:21)   5 | export async function getFavorite() {   6 |   "use cache";>  7 |   const id = (await cookies()).get("favorite")?.value ?? "green";     |                     ^   8 |   const response = await fetch(`${api}/teas/${id}`);   9 |   return response.json();  10 | } {  digest: '3275836682'}Error: Route "/teas": `cookies()` can't be read inside `"use cache"`. Read it outside the cached function and pass what you need as an argument.Learn more: https://nextjs.org/docs/messages/next-request-in-use-cache    at g (lib/supplier.ts:7:21)   5 | export async function getFavorite() {   6 |   "use cache";>  7 |   const id = (await cookies()).get("favorite")?.value ?? "green";     |                     ^   8 |   const response = await fetch(`${api}/teas/${id}`);   9 |   return response.json();  10 | } {  digest: '3275836682'}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" 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". Read more: https://nextjs.org/docs/messages/prerender-errorExport encountered an error on /teas/page: /teas, exiting the build.⨯ Next.js build worker exited with code: 1 and signal: null

Line 7 reads the favorite cookie inside getFavorite, which is cached on line 6. The build stopped: cookies() can't be read inside "use cache". Read it outside the cached function and pass what you need as an argument. headers() and searchParams have messages of their own that say the same (use-cache-messages.ts, lines 35 to 63). The docs add that the rule follows the calls: a helper the cached function calls can't read them either. Read the cookie in the component, inside Suspense, and pass its value: that's the "both" pattern from Cache Components, and exercise 3 below.

Passing children through a cache

A cached component can take children, or any other prop that holds JSX, and put it in what it renders without looking at it. Then the JSX passes through: it's not part of the key, and not part of the stored copy. Each request fills it in. Here a cached TeaCard shows mint tea with a greeting inside it:

1import type { ReactNode } from "react";2 3const api = process.env.SUPPLIER_API_URL;4 5export async function TeaCard({ id, children }: { id: string; children: ReactNode }) {6  "use cache";7  const response = await fetch(`${api}/teas/${id}`);8  const tea = await response.json();9  return (10    <section>11      <h2>{tea.name}</h2>12      <p>${tea.price} a box</p>13      {children}14    </section>15  );16}

In app/tea-card.tsx, TeaCard on lines 5 to 16 is cached on line 6 and fetches the tea on line 7. Line 13 puts children in its output, and nothing else touches them. In app/teas/page.tsx, MintForYou reads the visitor's name from a cookie on line 6 and passes a <p> with it as children, on lines 8 to 10.

Asha and Ben each saw their own name inside the same card, and the supplier was asked for /teas/mint once. The card was stored once; each visit put its own greeting in the hole.

Only JSX passes through. Text is a value like any argument, so text children become part of the key. The second version below passes the greeting as text:

1import { Suspense } from "react";2import { cookies } from "next/headers";3import { TeaCard } from "@/app/tea-card";4 5async function MintForYou() {6  const name = (await cookies()).get("name")?.value ?? "friend";7  return (8    <TeaCard id="mint">9      <p>Picked for you, {name}.</p>10    </TeaCard>11  );12}13 14export default function TeasPage() {15  return (16    <main>17      <h1>Our teas</h1>18      <Suspense fallback={<p>Picking a tea…</p>}>19        <MintForYou />20      </Suspense>21    </main>22  );23}

With text, Picked for you, Asha. and Picked for you, Ben. made two keys, and mint was fetched twice. Wrapping the text in an element keeps one copy for every visitor. The docs add one rule: the cached component must not read or change what passes through, only place it. The same works for a Server Action passed through to a Client Component, as long as the cached component doesn't call it.

Caching data or caching UI

Next.js's docs call the two main uses data-level and UI-level caching. On a data function, the directive stores data, and any component can render it. On a component, it stores what the component rendered, for those props. The shop's menu can be sorted by name or by price, from ?sort= in the address. Each version below was visited with name, then price twice:

1import { Suspense } from "react";2 3const api = process.env.SUPPLIER_API_URL;4 5type Tea = { id: string; name: string; price: number };6 7async function Menu({ sort }: { sort: string }) {8  "use cache";9  const response = await fetch(`${api}/menu`);10  const teas: Tea[] = await response.json();11  const sorted = sort === "price" ? teas.toSorted((a, b) => a.price - b.price) : teas;12  return (13    <ul>14      {sorted.map((tea) => (15        <li key={tea.id}>16          {tea.name}: ${tea.price}17        </li>18      ))}19    </ul>20  );21}22 23async function SortedMenu({ searchParams }: Pick<PageProps<"/teas">, "searchParams">) {24  const { sort = "name" } = await searchParams;25  return <Menu sort={String(sort)} />;26}27 28export default function TeasPage({ searchParams }: PageProps<"/teas">) {29  return (30    <main>31      <h1>Our teas</h1>32      <Suspense fallback={<p>Loading the menu…</p>}>33        <SortedMenu searchParams={searchParams} />34      </Suspense>35    </main>36  );37}

Cached as UI, Menu got one entry for each sort, so the supplier was asked for /menu twice. Cached as data, getMenu has no arguments, so one entry served both orders, and Menu sorted it for each visit. Each row compares the two:

Start with the data. Cache a component when rendering it is the work you want to save, and its props take few different values. Both can be combined: a cached component can call a cached function.

Will it work in a cache?

Every card below is something the recordings tried inside "use cache". Sort each one by what happened:

The pattern: plain values in and out, request data read outside, JSX passed through untouched, and async always.

Common mix-ups

• "The cache key is the function's name." No. It's the build, the function, its arguments, and the values it captures. "mint" and "green" are two entries.
• "Children are cached with the component." No. JSX children pass through and are filled in for each request. Text children are values, and do join the key.
• "If the build passes, the cached function is fine." Not always. A cached call inside a part that waits for the request first runs during a visit: the class argument failed only then.
• "Inside Suspense, a cached function can read cookies." No. Request data is never read inside "use cache". Read it outside and pass the value in.
• "What the build cached, every route can reuse." No. The build's copies went into the prerendered output of the routes that used them. A visit that called getTea("mint") asked the supplier again.
• "A file-level directive caches the whole module." No. It caches each exported function, and every one must be async.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

const api = process.env.SUPPLIER_API_URL;

export type Tea = { id: string; name: string; price: number };

export async function getTea(id: string): Promise<Tea> {
  "use cache";
  const response = await fetch(`${api}/teas/${id}`);
  return response.json();
}

const api = process.env.SUPPLIER_API_URL;

export function getTea(id: string) {
  "use cache";
  return fetch(`${api}/teas/${id}`).then((response) => response.json());
}

const api = process.env.SUPPLIER_API_URL;

export type Tea = { id: string; name: string; price: number };

export async function getTea(id: string): Promise<Tea> {
  "use cache";
  const response = await fetch(`${api}/teas/${id}`);
  return response.json();
}

import { cookies } from "next/headers";

const api = process.env.SUPPLIER_API_URL;

export async function getFavorite() {
  "use cache";
  const id = (await cookies()).get("favorite")?.value ?? "green";
  const response = await fetch(`${api}/teas/${id}`);
  return response.json();
}

import { Suspense } from "react";
import { cookies } from "next/headers";
import { getTea } from "@/lib/supplier";

async function Favorite() {
  const id = (await cookies()).get("favorite")?.value ?? "green";
  const tea = await getTea(id);
  return <p>Your favorite: {tea.name}</p>;
}

export default function TeasPage() {
  return (
    <main>
      <h1>Our teas</h1>
      <Suspense fallback={<p>Finding your favorite…</p>}>
        <Favorite />
      </Suspense>
    </main>
  );
}

const api = process.env.SUPPLIER_API_URL;

export class TeaId {
  constructor(public value: string) {}
}

export async function getTea(id: TeaId) {
  "use cache";
  const response = await fetch(`${api}/teas/${id.value}`);
  return response.json();
}

const api = process.env.SUPPLIER_API_URL;

export type Tea = { id: string; name: string; price: number };

export async function getTea(id: string): Promise<Tea> {
  "use cache";
  const response = await fetch(`${api}/teas/${id}`);
  return response.json();
}

import { Suspense } from "react";
import { cookies } from "next/headers";
import { TeaCard } from "@/app/tea-card";

async function MintForYou() {
  const name = (await cookies()).get("name")?.value ?? "friend";
  return (
    <TeaCard id="mint">{`Picked for you, ${name}.`}</TeaCard>
  );
}

export default function TeasPage() {
  return (
    <main>
      <h1>Our teas</h1>
      <Suspense fallback={<p>Picking a tea…</p>}>
        <MintForYou />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { cookies } from "next/headers";
import { TeaCard } from "@/app/tea-card";

async function MintForYou() {
  const name = (await cookies()).get("name")?.value ?? "friend";
  return (
    <TeaCard id="mint">
      <p>Picked for you, {name}.</p>
    </TeaCard>
  );
}

export default function TeasPage() {
  return (
    <main>
      <h1>Our teas</h1>
      <Suspense fallback={<p>Picking a tea…</p>}>
        <MintForYou />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";

const api = process.env.SUPPLIER_API_URL;

type Tea = { id: string; name: string; price: number };

async function Menu({ sort }: { sort: string }) {
  "use cache";
  const response = await fetch(`${api}/menu`);
  const teas: Tea[] = await response.json();
  const sorted = sort === "price" ? teas.toSorted((a, b) => a.price - b.price) : teas;
  return (
    <ul>
      {sorted.map((tea) => (
        <li key={tea.id}>
          {tea.name}: ${tea.price}
        </li>
      ))}
    </ul>
  );
}

async function SortedMenu({ searchParams }: Pick<PageProps<"/teas">, "searchParams">) {
  const { sort = "name" } = await searchParams;
  return <Menu sort={String(sort)} />;
}

export default function TeasPage({ searchParams }: PageProps<"/teas">) {
  return (
    <main>
      <h1>Our teas</h1>
      <Suspense fallback={<p>Loading the menu…</p>}>
        <SortedMenu searchParams={searchParams} />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";

const api = process.env.SUPPLIER_API_URL;

type Tea = { id: string; name: string; price: number };

async function getMenu(): Promise<Tea[]> {
  "use cache";
  const response = await fetch(`${api}/menu`);
  return response.json();
}

async function Menu({ sort }: { sort: string }) {
  const teas = await getMenu();
  const sorted = sort === "price" ? teas.toSorted((a, b) => a.price - b.price) : teas;
  return (
    <ul>
      {sorted.map((tea) => (
        <li key={tea.id}>
          {tea.name}: ${tea.price}
        </li>
      ))}
    </ul>
  );
}

async function SortedMenu({ searchParams }: Pick<PageProps<"/teas">, "searchParams">) {
  const { sort = "name" } = await searchParams;
  return <Menu sort={String(sort)} />;
}

export default function TeasPage({ searchParams }: PageProps<"/teas">) {
  return (
    <main>
      <h1>Our teas</h1>
      <Suspense fallback={<p>Loading the menu…</p>}>
        <SortedMenu searchParams={searchParams} />
      </Suspense>
    </main>
  );
}

Check your understanding

For each question, ask what goes into the key, and whether it can be stored.

Key takeaways

• "use cache" goes at the top of an async function, a component, or a file. In a file, every exported function is cached and must be async.
• The cache key is the build's ID, the function's ID, the arguments, and the values the function captures. Same key, same stored copy.
• Arguments and results must be serializable. Class instances and functions can only pass through, and request data is read outside the cache and passed in.
• JSX children pass through a cached component: not in the key, filled in for each request. Text children join the key.
• Data-level caching shares one entry between every component that reads it; UI-level caching stores one rendering for each set of props.
• Without cacheLife, the default lifetime applies: revalidate is 15 minutes, and in this version the in-memory store drops a copy after that. During the build, copies go into the prerendered output of the routes that use them; in next start, into the server's memory.

Coming next: Cache lifetimes and tags. cacheLife decides how long a stored copy stays fresh, and cacheTag names it, so you can expire it later.