How it works
The compiler turns every function under 'use cache' into a call through a cache wrapper that knows the function's ID. Variables the function closes over are captured and bound as extra arguments (the docs' wording). The argument list is serialized with React's Server Components serialization and combined with the build ID and function ID into the key. On a hit, the stored RSC output is replayed; on a miss, the function runs in an isolated scope (its own React cache scope, for instance), and the serialized result goes to the cache handler as a stream, described by the CacheEntry type in the cacheHandlers docs.
Two things follow. Keys compare the serialized form, not values, so key order inside objects and the difference between 1 and '1' both matter, as the Example showed. And the closure rule means you can't hide an input: the docs' example of an inner getData(filter) that reads userId from its component gets one entry per userId and filter pair. I ran it with ?u=alice twice and ?u=bob once and saw RUN closure alice active and RUN closure bob active, nothing more.
The four directive placements behave the same way underneath:
- Function level: a data helper, keyed by its arguments.
- Component level: keyed by props; the stored value is RSC output.
- File level: every export is cached and must be async.
getA(x) in a 'use cache' module ran once for two requests with the same x.
- Route segment:
'use cache' at the top of page or layout, the same file-level rule; the docs note each segment is its own entry.
Edge cases
Pass-through is a hole, not a key. A cached Card received children that read cookies() inside <Suspense>:
// app/comp/page.jsx
async function Card({ id, children }) {
'use cache';
const n = (await (await fetch(`http://localhost:4999/card?id=${id}`)).json()).n;
return <section>card {id} n={n} {children}</section>;
}
export default function Page() {
return <Card id="7"><Suspense fallback={<i>…</i>}><Who /></Suspense></Card>;
}
Card ran once during the build and never at request time; requests with who=sam and who=kim cookies each showed their own who= value inside the same cached card. The children are serialized as a reference slot, so they neither enter the key nor get frozen in the entry.
Unsupported arguments fail late, and not always. The docs list class instances, functions, symbols and URL as unsupported. In 16.4.5 a class instance or function only failed when the cached code read or called it (the errors in Pitfalls), at build time for a static route. A URL didn't fail at all: inside the function it was a string (typeof url printed string, url.pathname was undefined): its href, what JSON.stringify gives for a URL. The page rendered an empty paragraph with no warning.
Request-time entries are per process. The default handler for both use cache and use cache: remote is an in-memory LRU, sized by cacheMaxMemorySize. After restarting next start on the same build, every request-time entry re-ran (the API counter went from 1 to 2 for each argument). The .next/cache folder got no new files.
Real-world scenario
A catalogue page caches getProducts(filters) where filters comes from searchParams. Every combination of filters, and every ordering of the same filters in the object, is a new entry, so the hit rate is close to zero and memory fills with one-off results. Normalising the input (sorted keys, or a small set of strings) and caching on the low-cardinality dimension, then filtering in memory, fixes both. The use cache: remote docs make the same recommendation for remote handlers, where each miss also costs a network round trip.
Trade-offs
Automatic keys remove the hand-maintained key arrays of unstable_cache and can't forget a closed-over variable, but you lose control over what is not in the key: anything the function closes over or receives counts. Keying on build ID makes deploys safe (no old-shape data reaching new code) at the cost of a cold cache after every deploy. And the default handler's per-process memory means request-time caching is a best-effort optimisation on serverless or multi-instance hosting; for shared, durable entries you configure cacheHandlers.