Cache scopes

One probe, a random.org integer that differs on every upstream call, goes through five different caches. Two panels that show the same number share a cache entry.

The private panel is the only one permitted to read cookies() and headers() inside its own cached scope. The other four throw next-request-in-use-cache if they try, and the restriction follows the call stack, so a helper that reads a cookie fails the same way.

What to check

Shared against private. Open this page in two different browsers, or one normal and one private window. The shared and remote panels show the same number in both. The private panel differs, because it re-executes on every request.

Private is not persisted. Reload the private window. The private panel changes even inside its stale window, because nothing was written to a server cache and the client cache does not survive a page load.

Check both handlers. Run CACHE_DEBUG=true pnpm start and watch the handler logs while reloading. The shared and remote panels should log lookups; the private panel should log nothing.

The legacy path. Invalidate scope:legacy-fetch below. That tag only exists on a fetch(…, { next: { tags } }) call, so if that panel moves, the singular cacheHandler is alive and honouring tags. Do the same with scope:unstable-cache for the unstable_cache panel.

Shared server caches

Every visitor and every server instance sees both. They can be prerendered, so they need no Suspense boundary.

'use cache'

use cache

cacheLife: blog
cacheTag: scope:shared
upstream: 246ms

ran at 21:30:41.523Zexec 37eov8age …

probe 117,154

Stored via cacheHandlers.default. Shared across every visitor and every server instance.

'use cache: remote'

use cache: remote

cacheLife: blog
cacheTag: scope:remote
upstream: 209ms

ran at 21:30:41.837Zexec 6fz9wgage …

probe 137,540

Stored via cacheHandlers.remote. Durable and shared across all server instances.

Per-client and legacy

None is in the static shell. The private scope never is, and both legacy scopes await connection() first. All three need <Suspense>.

'use cache: private'

use cache: private

cacheLife: minutes
upstream: 258ms

ran at 21:30:43.170Zexec 49s9c3age …

probe 192,511

Read runtime request APIs inside the cache scope. visitor=(no `visitor` cookie set), ua="Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Geck…". Never written to a server cache; held in browser memory for the stale window only.

'use cache: private'

suspense fallback

streaming at request time. This is what ships in the static shell.

fetch force-cache (legacy)

fetch force-cache

cacheLife: next.revalidate: 300
cacheTag: scope:legacy-fetch
upstream: 257ms

ran at 21:30:43.166Zexec per-renderage …

probe 87,664

Legacy path: cached by the singular `cacheHandler`, not `cacheHandlers`. Judge hits by the probe value. The stamp here is per render, since only the fetch is cached.

fetch force-cache (legacy)

suspense fallback

streaming at request time. This is what ships in the static shell.

unstable_cache (legacy)

unstable_cache

cacheLife: revalidate: 300
cacheTag: scope:unstable-cache
upstream: 202ms

ran at 21:30:43.113Zexec 25ykivage …

probe 115,016

Legacy path: cached by the singular `cacheHandler`. The stamp is taken inside the cached function, so it moves only on a refill.

unstable_cache (legacy)

suspense fallback

streaming at request time. This is what ships in the static shell.

Invalidate per scope

Each scope has its own tag

revalidateTag('scope:shared', { expire: 0 }): Only the 'use cache' panel should move.
revalidateTag('scope:remote', { expire: 0 }): Only the remote panel should move.
revalidateTag('scope:legacy-fetch', { expire: 0 }): Tagged with fetch's next.tags instead of cacheTag. If the panel moves, the legacy cacheHandler honours tags.
revalidateTag('scope:unstable-cache', { expire: 0 }): Tagged through unstable_cache's options. Only the unstable_cache panel should move.

There is no tag for the private scope, and no button for it. Private cache entries are never written to a server cache, so there is nothing for a tag to invalidate. The stale window is the only control over them.

The three directives, side by side

	use cache	use cache: remote	use cache: private
Server-side storage	cacheHandlers.default	cacheHandlers.remote	none
Cache scope	all users	all users	one client
May read cookies()/headers()	no, pass as arguments	no, pass as arguments	yes
In the static shell	yes, if long-lived enough	yes, if long-lived enough	never
Invalidated by cacheTag	yes	yes	no
Survives a page reload	yes	yes	no
Survives a deploy	no	no	n/a

Use remote when a scope resolves at request time instead of in the shell. Each serverless instance has its own memory, so a shared store raises the hit rate. For shell content, plain use cache is usually enough.