Caching under the hood

From 'use cache' to a stored entry

'use cache', cache lifetimes and tags and revalidating data showed what caching does from your code. Underneath, Next.js 16.4.3 runs a cached function through a wrapper, in server/use-cache/use-cache-wrapper.ts, which builds a key, looks for a stored result, and stores a new one through a cache handler: an object with get and set methods that keeps the entries. An entry is one stored result: the function's encoded output, plus its lifetimes and its tags. A tag is a name given to entries so they can be expired together.

The app is the tea shop's menu. getMenu is cached for an hour and tagged menu; /menu shows it in the currency of the address, and /today greets the visitor by a cookie. To watch the cache from outside, the project's next.config.ts sets cacheHandlers.default to a file that wraps Next.js's own built-in handler and prints every call. It reaches into an internal path of next, so it's a study tool for this version, never something for an app. This is a real Next.js 16.4.3 project, built with next build and run with next start, and the recorder asked for /today, then /menu?currency=usd twice, then /menu?currency=eur. Open the Terminal tab:

1import { cacheLife, cacheTag } from "next/cache";2 3export async function getMenu(currency: string) {4  "use cache";5  cacheLife("hours");6  cacheTag("menu");7  console.log(`getMenu ran for ${currency}`);8  const prices = currency === "eur" ? ["€3", "€4"] : ["$3", "$4"];9  return [10    { name: "Mint tea", price: prices[0] },11    { name: "Green tea", price: prices[1] },12  ];13}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled- Experiments (use with caution):  ⨯ turbopackMinify   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...refreshTagsget ["c06e3edb815bb6354db1ce78f96faf8ca2bba9280b",["usd"],["<buildId>"]] missinggetMenu ran for usdset ["c06e3edb815bb6354db1ce78f96faf8ca2bba9280b",["usd"],["<buildId>"]] {"tags":["menu"],"stale":300,"revalidate":3600,"expire":86400}✓ Generating static pages (4/4)  Finalizing page optimization ... Route (app)      Revalidate  Expire┌ ○ /_not-found├ ◐ /menu└ ◐ /today               1h      1d ○  (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✓ ReadyrefreshTagsget ["c06e3edb815bb6354db1ce78f96faf8ca2bba9280b",["usd"],["<buildId>"]] missinggetMenu ran for usdset ["c06e3edb815bb6354db1ce78f96faf8ca2bba9280b",["usd"],["<buildId>"]] {"tags":["menu"],"stale":300,"revalidate":3600,"expire":86400}refreshTagsget ["c06e3edb815bb6354db1ce78f96faf8ca2bba9280b",["usd"],["<buildId>"]] found, revalidate 3600getExpiration ["_N_T_/layout","_N_T_/menu/layout","_N_T_/menu/page","_N_T_/menu"] never revalidatedrefreshTagsget ["c06e3edb815bb6354db1ce78f96faf8ca2bba9280b",["eur"],["<buildId>"]] missinggetMenu ran for eurset ["c06e3edb815bb6354db1ce78f96faf8ca2bba9280b",["eur"],["<buildId>"]] {"tags":["menu"],"stale":300,"revalidate":3600,"expire":86400}

In lib/menu.ts, line 4 makes getMenu a cached function, line 5 gives it the hours lifetime and line 6 the tag menu. Line 7 prints a line each time the function really runs. Here is what the handler printed under next start (each key's long function id cut to its first characters):

refreshTags
get ["c06e3edb…",["usd"],["<buildId>"]] missing
getMenu ran for usd
set ["c06e3edb…",["usd"],["<buildId>"]] {"tags":["menu"],"stale":300,"revalidate":3600,"expire":86400}
refreshTags
get ["c06e3edb…",["usd"],["<buildId>"]] found, revalidate 3600
getExpiration ["_N_T_/layout","_N_T_/menu/layout","_N_T_/menu/page","_N_T_/menu"] never revalidated
refreshTags
get ["c06e3edb…",["eur"],["<buildId>"]] missing
getMenu ran for eur
set ["c06e3edb…",["eur"],["<buildId>"]] {"tags":["menu"],"stale":300,"revalidate":3600,"expire":86400}

1. /today came first, and printed nothing at all. Lines 1 to 4 are the first visit to /menu in dollars: get found nothing, getMenu ran, and set stored the result.
2. Lines 5 to 7, the second visit: get found it, and getMenu didn't run.
3. Lines 8 to 11, euros: a different key, so another miss, run and store.

The 'use cache' wrapper

The compiler, SWC (SWC and Turbopack showed it), rewrites every "use cache" function. The recorder kept the module the build made from lib/menu.ts (with Turbopack's minifier off, line 10 of next.config.ts). With the bundler's module names replaced by the names the transform gives those imports (server_actions.rs, lines 2586 and 2587), it reads:

const $$RSC_SERVER_CACHE_0_INNER = async function getMenu(currency) {
    cacheLife("hours");
    cacheTag("menu");
    console.log(`getMenu ran for ${currency}`);
    // … the rest of getMenu, as written
};
var $$RSC_SERVER_CACHE_0 = $$reactCache__(function getMenu() {
    return $$cache__("default", "c06e3edb815bb6354db1ce78f96faf8ca2bba9280b", 0, $$RSC_SERVER_CACHE_0_INNER, Array.prototype.slice.call(arguments, 0, 1));
});
registerServerReference($$RSC_SERVER_CACHE_0, "c06e3edb815bb6354db1ce78f96faf8ca2bba9280b", null);
Object["defineProperty"]($$RSC_SERVER_CACHE_0, "name", {
    value: "getMenu"
});
var getMenu = $$RSC_SERVER_CACHE_0;

1. Lines 1 to 6: your function, renamed $$RSC_SERVER_CACHE_0_INNER, its body unchanged.
2. Lines 7 and 8: the new getMenu. React's cache ($$reactCache__) shares one call's result within a render; inside it, $$cache__ gets the kind "default", the function's id, 0 bound arguments, your function, and the arguments of this call.
3. Line 10 registers it as a server reference with the same id, the way a Server Action is registered ('use client' and 'use server' under the hood).
4. Line 14: the name you export is the wrapper.

$$cache__ is cache from use-cache-wrapper.ts, lines 1867 to 1873:

export async function cache(
  kind: string,
  id: string,
  boundArgsLength: number,
  originalFn: (...args: unknown[]) => Promise<unknown>,
  args: unknown[]
) {

Line 2, kind, picks the handler: "default" for "use cache", "remote" for "use cache: remote" (lines 1943 to 1946: getCacheHandler(kind), or an error for an unknown one). Line 4 counts the values a closure captured, which come first, encrypted (Server Actions under the hood, later in this module, reads how). On a miss, the function runs like this, from lines 1360 to 1750:

const [, args] =
  typeof encodedArguments === 'string'
    ? await decodeReply<CacheKeyParts>(
        encodedArguments,
        getServerModuleMap(),
        { temporaryReferences }
      )
// …
const resultPromise = createLazyResult(fn.bind(null, ...args))
// …
    stream = renderToReadableStream(
      resultPromise,
      clientReferenceManifest.clientModules,
      {
        environmentName: 'Cache',
        filterStackFrame,
        temporaryReferences,
        onError: handleError,
      }
    )
// …
const [returnStream, savedStream] = stream.tee()

Lines 1 to 7 decode the arguments back out of the encoded key, with decodeReply. Line 9 calls your function with them: it sees exactly what the key holds, never the original objects. Lines 11 to 20 render the result with React's Flight server, renderToReadableStream, the same format as the RSC payload. Line 22 copies the stream: one copy goes back to the caller, the other becomes the entry the handler's set receives. That's why a cached function may return only what Flight can encode ('use cache' listed it).

What goes into a cache key

The key comes from three parts, in use-cache-wrapper.ts, lines 2289 to 2297:

const { implementationPart, runtimeEnvVarStateHash } =
  await computeCacheKeyImplementationPart(workStore, workUnitStore, id)
const cacheKeyParts: CacheKeyParts = [id, args, implementationPart]

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

Line 3: the function's id, the arguments, and an implementation part. Lines 5 to 9 encode the list with encodeReply, React's encoder for values sent to the server, the one Server Actions use for their arguments; for plain values like these, the result is a string of JSON. The implementation part, from lines 3917 to 3931:

const buildId = workStore.deploymentId || workStore.buildId
// …
const hmrRefreshHash = getHmrRefreshHash(workUnitStore)
// …
return {
  implementationPart: hmrRefreshHash
    ? [buildId, hmrRefreshHash]
    : [buildId],
  runtimeEnvVarStateHash: undefined,

Line 1: the deployment's id if you set one (deploymentId in next.config.ts), otherwise the build's. Lines 5 to 8: in next dev, a hash that changes when you edit a Server Component joins it. So a new build starts with new keys: the source's comment above line 1 says the build's id is there because ids don't yet change with the code. (With experimental.durableUseCacheEntries, the part is a hash of the code and the Next.js version instead, lines 3872 to 3911.) The recording shows the key as the handler got it, with the build's id replaced by <buildId>: line 2 of the log is ["c0…",["usd"],["<buildId>"]], and euros, line 9, differ only in the middle.

The first part is the id from line 8 of the compiled code. The build's server reference manifest lists it, with the file and the pages that use it (recorded, the encryption key hidden):

self.__RSC_SERVER_MANIFEST="{\n  \"node\": {\n    \"c06e3edb815bb6354db1ce78f96faf8ca2bba9280b\": {\n      \"workers\": {\n        \"app/menu/page\": {\n          \"moduleId\": 95511,\n          \"async\": false\n        },\n        \"app/today/page\": {\n          \"moduleId\": 19306,\n          \"async\": false\n        }\n      },\n      \"filename\": \"lib/menu.ts\",\n      \"exportedName\": \"$$RSC_SERVER_CACHE_0\"\n    }\n  },\n  \"edge\": {},\n  \"encryptionKey\": \"<encryptionKey>\"\n}"

The id names lib/menu.ts's $$RSC_SERVER_CACHE_0, used by app/menu/page and app/today/page. A private cache ("use cache: private") adds nothing about cookies to this key in production: its entries never reach a handler (Private and remote caches).

cacheLife defaults in config-shared

The set line of the log shows the lifetime the entry was stored with: {"stale":300,"revalidate":3600,"expire":86400}, in seconds. Those numbers are the hours profile, from the default config, in config-shared.ts, lines 2346 to 2379:

cacheLife: {
  default: {
    stale: undefined, // defaults to staleTimes.static
    revalidate: 60 * 15, // 15 minutes
    expire: INFINITE_CACHE,
  },
  seconds: {
    stale: 30, // 30 seconds
    revalidate: 1, // 1 second
    expire: 60, // 1 minute
  },
  minutes: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60, // 1 minute
    expire: 60 * 60, // 1 hour
  },
  hours: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60 * 60, // 1 hour
    expire: 60 * 60 * 24, // 1 day
  },
  days: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60 * 60 * 24, // 1 day
    expire: 60 * 60 * 24 * 7, // 1 week
  },
  weeks: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60 * 60 * 24 * 7, // 1 week
    expire: 60 * 60 * 24 * 30, // 1 month
  },
  max: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60 * 60 * 24 * 30, // 1 month

Lines 17 to 21 are hours: 5 minutes, an hour, a day. Line 3: default has no stale of its own and uses staleTimes.static, 300 seconds unless you change it. Line 5: INFINITE_CACHE, never expires. The whole table, to read:

Your cacheLife option in next.config.ts is merged over this table. The function cacheLife() looks a name up in it and keeps the shortest time, shortened from cache-life.ts, lines 56 to 103:

if (typeof profile === 'string') {
  const workStore = workAsyncStorage.getStore()
// …
  const configuredProfile = workStore.cacheLifeProfiles[profile]
// …
  profile = configuredProfile
// …
if (profile.revalidate !== undefined) {
  // Track the explicit revalidate time.
  if (
    workUnitStore.explicitRevalidate === undefined ||
    workUnitStore.explicitRevalidate > profile.revalidate
  ) {
    workUnitStore.explicitRevalidate = profile.revalidate
  }
}

Line 4 reads the profile by name from workStore.cacheLifeProfiles (your profiles merged over the table, in config.ts, lines 1490 to 1500). Lines 8 to 16 store its revalidate on the cache's own store unless a shorter one is there already; expire and stale follow on the next lines of the file. So two cacheLife calls in one function keep the shortest. The build printed the route's result too: ◐ /today with 1h and 1d in the Revalidate and Expire columns of the Terminal tab.

Cache handlers and the incremental cache

Every handler, built-in or yours, has the same five methods, from lib/cache-handlers/types.ts, lines 68 to 117 (the left-out lines are comments):

export interface CacheHandler {
// …
  get(cacheKey: string, softTags: string[]): Promise<undefined | CacheEntry>
// …
  set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>
// …
  refreshTags(): Promise<void>
// …
  getExpiration(tags: string[]): Promise<Timestamp>
// …
  updateTags(tags: string[], durations?: { expire?: number }): Promise<void>
}

• Line 3, get: an entry for a key, or nothing. It also gets the request's soft tags, the tags a route gets from its path (they're read below).
• Line 5, set: store an entry that may still be streaming in. The comments say Next.js never deletes entries itself; the handler must evict them.
• Line 7, refreshTags: called once per request before its first read, as the log printed.
• Line 9, getExpiration: when a set of tags was last revalidated.
• Line 11, updateTags: mark tags revalidated, with an optional expire.

Without cacheHandlers, both default and remote are one built-in handler, from use-cache/handlers.ts, lines 106 to 113:

} else {
  const handler = createDefaultCacheHandler(builtInSize)
  builtInHandlers.add(handler)

  debug?.('setting "default" cache handler from default')
  handlersMap.set('default', handler)
  debug?.('setting "remote" cache handler from default')
  handlersMap.set('remote', handler)

Line 2 makes it with builtInSize, the cacheMaxMemorySize option: 50 MB by default. It's an LRU, a store that drops the least recently used entries when it's full, in this server's memory. Its get, from cache-handlers/default.ts, lines 114 to 137:

const maxAgeSeconds = process.env.__NEXT_DEV_SERVER
  ? Math.max(entry.expire, MIN_PRERENDERABLE_EXPIRE)
  : entry.revalidate

if (
  performance.timeOrigin + performance.now() >
  entry.timestamp + maxAgeSeconds * 1000
) {
  debug?.('get', cacheKey, 'expired')

  return undefined
}

let revalidate = entry.revalidate

if (areTagsExpired(entry.tags, entry.timestamp)) {
  debug?.('get', cacheKey, 'had expired tag')
  return undefined
}

if (areTagsStale(entry.tags, entry.timestamp)) {
  debug?.('get', cacheKey, 'had stale tag')
  revalidate = -1
}

1. Lines 1 to 3: in production, an entry may live revalidate seconds, not expire. Lines 5 to 12: older ones are a miss. So with the built-in handler of this version, an hour-old getMenu result is filled again at the next call, in the foreground. A handler of your own may keep it until expire, and then Next.js serves it and refreshes it in the background.
2. Lines 16 to 19: an entry with an expired tag is a miss too.
3. Lines 21 to 24: one with a stale tag is returned with revalidate = -1, which means "serve it, but replace it".

The incremental cache

Prerendered pages, Route Handler answers and the pages ISR regenerates are kept by a different store, the incremental cache, configured with cacheHandler (singular). Without one, it's the file-system cache, from incremental-cache/index.ts, lines 222 to 238:

if (!CurCacheHandler) {
// …
  } else {
    if (fs && serverDistDir) {
      if (IncrementalCache.debug) {
        console.log('IncrementalCache: using filesystem cache handler')
      }
      CurCacheHandler = FileSystemCache
    }
  }

Line 8: FileSystemCache, which keeps a memory LRU and files. Where the files go, from file-system-cache.ts, lines 742 to 760:

private getFilePath(key: string, kind: IncrementalCacheKind): string {
  let rootDir: string
  switch (kind) {
    case IncrementalCacheKind.FETCH:
      // we store in .next/cache/fetch-cache so it can be persisted
      // across deploys
      rootDir = path.join(this.serverDistDir, '..', 'cache', 'fetch-cache')
      break
    case IncrementalCacheKind.PAGES:
      rootDir = path.join(this.serverDistDir, 'pages')
      break
    case IncrementalCacheKind.IMAGE:
    case IncrementalCacheKind.APP_PAGE:
    case IncrementalCacheKind.APP_ROUTE:
      rootDir = path.join(this.serverDistDir, 'app')
      break
    default:
      throw new Error(`Unexpected file path kind: ${kind}`)
  }

Lines 13 to 15: pages and Route Handler answers go under .next/server/app, beside the files the build wrote. (Pages regenerated at runtime get a key under route-cache, a folder beside it in this version; Incremental Static Regeneration recorded one.) Lines 4 to 8: the older fetch cache goes to .next/cache/fetch-cache. Each row is one kind of cached thing, and where this version keeps it:

The resume data cache

Why did /today print nothing? Its Greeting reads the cookie, so the route is ◐: the build prerenders a static shell and saves what's needed to finish it for a request, the postponed state (Prerendering and Partial Prerendering, earlier in this stage, reads it). But the build ran Greeting up to the cookie, and getMenu("usd") comes before it. The build printed what it did:

get ["c06e3edb…",["usd"],["<buildId>"]] missing
getMenu ran for usd
set ["c06e3edb…",["usd"],["<buildId>"]] {"tags":["menu"],"stale":300,"revalidate":3600,"expire":86400}

Lines 1 to 3: the build missed, ran getMenu and stored the entry in its own memory, gone when the build ends. It also kept the entry with the route, in its resume data cache: the cached results the prerender filled. When the route is resumed for a request, that cache is read first, from use-cache-wrapper.ts, lines 2461 to 2839:

const resumeDataCache = getResumeDataCache(workUnitStore)
// …
if (resumeDataCache) {
// …
  let rdcEntry = resumeDataCache.cache.get(serializedCacheKey)
// …
    if (rdcResult !== undefined) {
      debug?.(logPrefix, 'Resume Data Cache entry found', serializedCacheKey)

Line 5 looks the key up in it, and line 8 is the hit: no handler is asked, so the request printed no refreshTags and no get. /menu had no such luck: its prerender stopped at searchParams, before getMenu, so its first visit missed in the handler, though the build had filled the same key for /today. The resume data cache is saved with the postponed state, compressed, at the end of the route's .meta file; Prerendering and Partial Prerendering took that value apart. The recorder kept .next/server/app/today.meta. Decompressed, its one cached entry is:

key: ["c06e3edb…",["usd"],["<buildId>"]]
tags: ["menu"]
stale: 300, revalidate: 3600, expire: 86400
value:
0:"$@1"
1:[{"name":"Mint tea","price":"$$3"},{"name":"Green tea","price":"$$4"}]

Line 1 is the key on line 1 of the build log. Lines 5 and 6 are the stored result: rows in the Flight format, like the RSC payload, with $$3 for the text $3 (The RSC payload reads $ values). The route's own cache tags are in the same file's headers: _N_T_/layout,_N_T_/today/layout,_N_T_/today/page,_N_T_/today,menu, so revalidating menu also reaches /today's saved shell.

Explicit and soft tags

A tag is a name that marks entries, so one call can expire all of them. There are two kinds. An explicit tag is one you give with cacheTag, from cache-tag.ts, lines 35 to 41:

const validTags = validateTags(tags, '`cacheTag()`')

if (!workUnitStore.tags) {
  workUnitStore.tags = validTags
} else {
  workUnitStore.tags.push(...validTags)
}

Lines 3 to 7 add the tags to the cache's store, and they end up in the entry: "tags":["menu"] in the set line. A soft tag (the source also calls them implicit tags) comes from the route that's being rendered, from lib/implicit-tags.ts, lines 26 to 57:

const getDerivedTags = (pathname: string): string[] => {
  const derivedTags: string[] = [`/layout`]
// …
  if (pathname.startsWith('/')) {
    let end = pathname.indexOf('/', 1)

// …
      let curPathname = pathname.slice(0, end)
      if (curPathname) {
        // all derived tags other than the page are layout tags
        if (!curPathname.endsWith('/page') && !curPathname.endsWith('/route')) {
          curPathname = `${curPathname}${
            !curPathname.endsWith('/') ? '/' : ''
          }layout`
        }
        derivedTags.push(curPathname)
// …
  return derivedTags
}

Line 2 starts with /layout, the root layout. Lines 8 to 16 add one tag per folder of the page's path, each ending in /layout, and the page itself. With the prefix _N_T_ and the request's own path added, a visit to /menu brings four: line 7 of the start log, ["_N_T_/layout","_N_T_/menu/layout","_N_T_/menu/page","_N_T_/menu"]. They're never stored in the entry; a read checks them, with getExpiration (printed only once an entry was found, since it's fetched when first needed). Here is the read that checks both kinds, from use-cache-wrapper.ts, lines 3269 to 3328:

entry = await cacheHandler.get(cacheHandlerKey, implicitTags)
// …
if (
  shouldDiscardCacheEntry(
    entry,
    workStore,
    workUnitStore,
    implicitTags,
    implicitTagsExpiration,
    logPrefix
  )
) {
  debug?.(logPrefix, 'discarding expired entry', cacheHandlerKey)
  entry = undefined
}

Line 1 asks the handler, passing the soft tags. Lines 3 to 15: a found entry is thrown away when shouldDiscardCacheEntry says one of its tags, or the soft tags' time from getExpiration (line 9), is later than the entry.

How revalidation reaches the handler

The three functions, shortened from web/spec-extension/revalidate.ts, lines 37 to 136:

export function revalidateTag(tag: string, profile: string | CacheLifeConfig) {
// …
  return revalidate(
    [encodeHeaderSafe(tag)],
    `revalidateTag(${JSON.stringify(tag)})`,
    profile
  )
}
// …
export function updateTag(tag: string) {
// …
  return revalidate(
    [encodeHeaderSafe(tag)],
    `updateTag(${JSON.stringify(tag)})`,
    undefined
  )
}
// …
export function revalidatePath(originalPath: string, type?: 'layout' | 'page') {
// …
  let normalizedPath = `${NEXT_CACHE_IMPLICIT_TAG_ID}${encodeHeaderSafe(removeTrailingSlash(originalPath))}`
// …
  const tags = [normalizedPath]
// …
  return revalidate(tags, `revalidatePath(${JSON.stringify(originalPath)})`)
}

Lines 3 to 7: revalidateTag passes its profile on. Lines 12 to 16: updateTag passes undefined, no profile. Lines 21 to 25: revalidatePath("/menu") turns the path into the soft tag _N_T_/menu, with no profile. All three call revalidate, which only writes them down, from lines 216 to 263:

if (!store.pendingRevalidatedTags) {
  store.pendingRevalidatedTags = []
}
// …
    store.pendingRevalidatedTags.push({
      tag,
      profile,
      revalidatedAt,
    })
// …
if (!profile || cacheLife?.expire === 0) {
  // TODO: only revalidate if the path matches
  store.pathWasRevalidated = ActionDidRevalidate
}

Lines 1 to 9 add each tag to pendingRevalidatedTags, with its profile and the time. Lines 11 to 13: without a profile (or with expire: 0), the action's page is rendered again, so it shows your own change. When the work is done, each handler gets the tags, grouped by profile, from revalidation-utils.ts, lines 169 to 184:

  if (cacheLife) {
    durations = {
      expire: cacheLife.expire,
    }
  }
// …
for (const handler of handlers) {
  if (profile) {
    promises.push(handler.updateTags?.(tagsForProfile, durations))
  } else {
    promises.push(handler.updateTags?.(tagsForProfile))
  }
}

Lines 1 to 5: a profile becomes durations, its expire only. Lines 8 to 12: with a profile, the handler gets the durations; without one, nothing more. The built-in handler then marks the tag, from default.ts, lines 218 to 241:

async updateTags(tags, durations) {
  const now = Math.round(performance.timeOrigin + performance.now())
// …
  for (const tag of tags) {
    // TODO: update file-system-cache?
    const existingEntry = tagsManifest.get(tag) || {}
// …
    if (durations) {
// …
      updates.stale = now

      if (durations.expire !== undefined) {
        updates.expired = now + durations.expire * 1000 // Convert seconds to ms
      }

      tagsManifest.set(tag, updates)
    } else {
      // Update expired field for immediate expiration (default behavior when no durations provided)
      tagsManifest.set(tag, { ...existingEntry, expired: now })
    }

Lines 8 to 16: with durations, the tag is stale now and expires expire seconds later. Line 19: without them, it's expired now. In the playground, the staff page's form calls one of the three in a Server Action. It's a stand-in: a real staff page checks who is asking first (Securing Server Actions). Pick each, and read the Terminal's last lines:

1import { updateTag } from "next/cache";2 3// A stand-in for a staff-only page: a real one checks who is asking first.4export default function StaffPage() {5  async function pricesChanged() {6    "use server";7    updateTag("menu");8  }9  return (10    <form action={pricesChanged}>11      <button>Prices changed</button>12    </form>13  );14}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled- Experiments (use with caution):  ⨯ turbopackMinify   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...refreshTagsget ["c070fa189ab1f4d1387ade5d8625d11d75c7195d99",["usd"],["<buildId>"]] missinggetMenu ran for usdset ["c070fa189ab1f4d1387ade5d8625d11d75c7195d99",["usd"],["<buildId>"]] {"tags":["menu"],"stale":300,"revalidate":3600,"expire":86400}✓ Generating static pages (5/5)  Finalizing page optimization ... Route (app)      Revalidate  Expire┌ ○ /_not-found├ ◐ /menu├ ○ /staff└ ◐ /today               1h      1d ○  (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✓ ReadyrefreshTagsget ["c070fa189ab1f4d1387ade5d8625d11d75c7195d99",["usd"],["<buildId>"]] missinggetMenu ran for usdset ["c070fa189ab1f4d1387ade5d8625d11d75c7195d99",["usd"],["<buildId>"]] {"tags":["menu"],"stale":300,"revalidate":3600,"expire":86400}refreshTagsget ["c070fa189ab1f4d1387ade5d8625d11d75c7195d99",["usd"],["<buildId>"]] found, revalidate 3600getExpiration ["_N_T_/layout","_N_T_/menu/layout","_N_T_/menu/page","_N_T_/menu"] never revalidatedupdateTags ["menu"] "no durations"updateTags ["menu"] "no durations"refreshTagsget ["c070fa189ab1f4d1387ade5d8625d11d75c7195d99",["usd"],["<buildId>"]] missinggetMenu ran for usdset ["c070fa189ab1f4d1387ade5d8625d11d75c7195d99",["usd"],["<buildId>"]] {"tags":["menu"],"stale":300,"revalidate":3600,"expire":86400}

updateTag and revalidatePath reached the handler twice: they ask for the action's page to render again, so the action handler applies pending revalidations before that render (action-handler.ts, lines 1509 to 1512), and app-render applies them again when it ends (app-render.tsx, lines 3177 and 3178). revalidateTag with a profile doesn't ask for that render, so its tags were applied once, at the end. After revalidateTag("menu", "max"), the visitor got the old menu: that's stale-while-revalidate, where the visit that finds a stale entry is served it and starts a refresh, and a later visit is fresh once that refresh has finished. The wrapper does it after a handler hit, in use-cache-wrapper.ts, lines 3696 to 3808:

stream = sharedCacheEntry.fork()
resolvableSharedCacheResult.resolve({
  type: 'cached',
  entry: sharedCacheEntry,
})
// …
let shouldTriggerBackgroundRevalidation =
  currentTime > entry.timestamp + entry.revalidate * 1000
// …
if (
  shouldTriggerBackgroundRevalidation &&
// …
  !backgroundRevalidations.has(cacheHandlerKey)
) {
// …
  const revalidatePromise = Promise.resolve()
    .then(() =>
      generateCacheEntry(
// …
  backgroundRevalidations.set(
    revalidateCacheHandlerKey,
    revalidatePromise
  )

Lines 1 to 5: the stored entry goes to this render, stale or not. Lines 7 and 8: it's stale once its revalidate seconds have passed, which a revalidate of -1 always has. Lines 10 to 18: unless a regeneration for this key is already running, generateCacheEntry runs the function again, and lines 20 to 23 keep that work in backgroundRevalidations, under the handler's key. (The recording doesn't print that second run: when it happens depends on timing.)

Each row is one call, what the handler gets, and what the next read of the menu gets:

Watching the caches in your own app

You can watch the same calls in your own app, in a production build. Use it to learn and to debug, never from your app's code:

• Write a handler of your own against the documented cacheHandlers interface that keeps entries in a Map and prints each call (Private and remote caches has one), and set it as cacheHandlers.default.
• Look at the build's route table: the Revalidate and Expire columns show the shortest lifetime each route's cached work has.
• Look in .next/server/app: a ◐ route's .meta file lists its cache tags in x-next-cache-tags.
• In this version, the environment variable NEXT_PRIVATE_DEBUG_CACHE=1 makes the wrapper and the built-in handlers print what they do. It's private: it may change or go away in any release.

Sort each value: is it part of the key, stored in the entry, or a soft tag the request brings?

Common mix-ups

• "The key is the function's name and its arguments." No. It's the compiler's id, the arguments as encoded, and the build's (or deployment's) id.
• "Entries the build filled are there when next start begins." No. The build's memory ends with it; only a ◐ route's resume data cache carries entries its own prerender filled, for that route.
• "The built-in handler keeps an entry until expire." No. In production in this version, its get drops an entry once revalidate has passed.
• "revalidateTag with a profile deletes the entry." No. It marks the tag stale: the next visit is served the old entry and starts a refresh. updateTag expires it now.
• "revalidatePath finds entries by their URL." No. It expires a soft tag, _N_T_/menu, which each request to that path checks with getExpiration.
• "A cached function receives the objects you passed." No. It receives the arguments decoded from the encoded key.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints. Some ask you to find a line in Next.js's source, and the excerpts above hold it.

get ["c06e3edb…",["usd"],["<buildId>"]] missing
getMenu ran for usd
get ["c06e3edb…",["usd"],["<buildId>"]] found, revalidate 3600
getExpiration ["_N_T_/layout","_N_T_/menu/layout","_N_T_/menu/page","_N_T_/menu"] never revalidated
get ["c06e3edb…",["eur"],["<buildId>"]] missing
getMenu ran for eur

cacheLife: {
  default: {
    stale: undefined, // defaults to staleTimes.static
    revalidate: 60 * 15, // 15 minutes
    expire: INFINITE_CACHE,
  },
  seconds: {
    stale: 30, // 30 seconds
    revalidate: 1, // 1 second
    expire: 60, // 1 minute
  },
  minutes: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60, // 1 minute
    expire: 60 * 60, // 1 hour
  },
  hours: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60 * 60, // 1 hour
    expire: 60 * 60 * 24, // 1 day
  },
  days: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60 * 60 * 24, // 1 day
    expire: 60 * 60 * 24 * 7, // 1 week
  },
  weeks: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60 * 60 * 24 * 7, // 1 week
    expire: 60 * 60 * 24 * 30, // 1 month
  },
  max: {
    stale: 60 * 5, // 5 minutes
    revalidate: 60 * 60 * 24 * 30, // 1 month

const buildId = workStore.deploymentId || workStore.buildId
// …
const hmrRefreshHash = getHmrRefreshHash(workUnitStore)
// …
return {
  implementationPart: hmrRefreshHash
    ? [buildId, hmrRefreshHash]
    : [buildId],
  runtimeEnvVarStateHash: undefined,

import { Suspense } from "react";
import { cookies } from "next/headers";
import { getMenu } from "@/lib/menu";

export default function TodayPage() {
  return (
    <main>
      <h1>Today</h1>
      <Suspense fallback={<p>Loading your tea…</p>}>
        <Greeting />
      </Suspense>
    </main>
  );
}

async function Greeting() {
  const menu = await getMenu("usd");
  const name = (await cookies()).get("name")?.value ?? "guest";
  return (
    <p>
      Hello, {name}. {menu[0].name} is {menu[0].price} today.
    </p>
  );
}

const maxAgeSeconds = process.env.__NEXT_DEV_SERVER
  ? Math.max(entry.expire, MIN_PRERENDERABLE_EXPIRE)
  : entry.revalidate

if (
  performance.timeOrigin + performance.now() >
  entry.timestamp + maxAgeSeconds * 1000
) {
  debug?.('get', cacheKey, 'expired')

  return undefined
}

let revalidate = entry.revalidate

if (areTagsExpired(entry.tags, entry.timestamp)) {
  debug?.('get', cacheKey, 'had expired tag')
  return undefined
}

if (areTagsStale(entry.tags, entry.timestamp)) {
  debug?.('get', cacheKey, 'had stale tag')
  revalidate = -1
}

export interface CacheHandler {
// …
  get(cacheKey: string, softTags: string[]): Promise<undefined | CacheEntry>
// …
  set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>
// …
  refreshTags(): Promise<void>
// …
  getExpiration(tags: string[]): Promise<Timestamp>
// …
  updateTags(tags: string[], durations?: { expire?: number }): Promise<void>
}

Check your understanding

For each question, ask where the value lives: in the key, in the entry, in a tag, or in a route's resume data.

Key takeaways

• The compiler turns a "use cache" function into a call to cache(kind, id, boundArgs, fn, args), inside React's cache.
• The key is [id, args, [buildId]], encoded with encodeReply; the function runs with the arguments decoded from it, and its result is stored in the Flight format.
• The built-in profiles are a table in config-shared.ts; cacheLife keeps the shortest time, and the entry carries it.
• The built-in handler is a 50 MB LRU in each server's memory, shared by default and remote; in production it drops entries after revalidate. Pages go to the incremental cache.
• A ◐ route's resume data cache carries entries its own prerender filled, and is read before any handler.
• Explicit tags live in entries; soft tags come from the route. updateTag expires now, revalidateTag with a profile marks stale, and revalidatePath expires a soft tag.

Coming next: Server Actions under the hood. It reads how an action's id is made, the Next-Action request, and how one response carries the result and the new UI.