A Next.js function marked with the `'use cache'` directive takes arguments and also reads a variable from its enclosing scope. What forms the cache key, and what does that require of the arguments and of the returned value?

## The key is the whole input surface A cache is only correct if its key captures everything that can change the answer. For a `'use cache'` function, Next builds that key from the call's inputs: the arguments passed in, serialized, plus the values the function captures from its enclosing scope. Two calls whose inputs serialize identically hit the same entry; any difference produces a different entry. ```ts export async function getFeed(userTier: string) { 'use cache' const res = await fetch(`https://api.example.com/feed?tier=${userTier}`) return res.json() } ``` Call this with `'free'` and with `'pro'` and you get two independent entries. Nothing about the fetch URL is inspected — it is the *arguments* that key the entry, not the requests the body happens to make. ## Closures count too This is the part candidates miss. If the cached function is defined inside another function and reads a variable from that outer scope, that captured value is part of the input surface and Next includes it: ```ts export function makeLoader(locale: string) { return async function load(slug: string) { 'use cache' return fetchArticle(slug, locale) // locale is closed over } } ``` Entries are separated by `slug` *and* `locale`. Contrast that with the predecessor API, `unstable_cache(fn, keyParts, options)`, where you supplied `keyParts` yourself: forgetting to list a closed-over value there produced a genuinely wrong cache — one locale's article served under another's key. Deriving the key from the actual closure removes an entire class of that bug. ## Serializability, in both directions Because the key is built by serializing inputs, and because the stored value is replayed rather than recomputed, serializability constrains both ends: - **Inputs** must be serializable to participate in the key. Plain objects, arrays, strings, numbers, dates — fine. A live database client, a class instance with methods, or a callback is not something that can be reduced to a stable key. - **The return value** must be serializable, because it is written into the cache and read back on a later request in a different process. Return plain data, not handles, streams, or closures. The practical rule: a cached function should look like a pure data function — data in, data out. ## What the key cannot see Anything the body reads that did not arrive as an input is invisible to the key. That includes: - **Mutable module state** — a `let` at module scope that something else updates. Two calls with the same arguments return the first call's answer forever. - **Time** — `Date.now()` inside the body is captured into the stored value, and every replay hands back the old timestamp. Lifetime belongs in `cacheLife()`, not in the body. - **Request-scoped data** — cookies, headers and search params. Reading them inside a cached function is not just a keying problem, it is a cross-user data-leak problem, which is why Next rejects it outright. When a value genuinely varies per call, the fix is always the same: make it an argument, so it becomes part of the key. ## Granularity is a design choice Because every distinct input combination is its own entry, key cardinality is something you choose. Passing a whole request object, or a timestamp, gives every call a unique key and a 0% hit rate — a cache that costs storage and returns nothing. Passing a narrow, low-cardinality parameter (`category`, `locale`, `tier`) gives a small set of hot entries. Before adding a parameter to a cached function, ask how many distinct values it will take in production. ## The mental model Think of the cached function as a lookup table Next fills in for you. The columns are the inputs it can see; the cell is the serialized result. Anything you want to vary the answer must be a column, and anything that cannot be written down as a column has no business being read inside the body.