Cache Inspector panel in Next.js DevTools: see why data is cached, stale, or dynamic

[HuseynAlizada]

Goals

1. Give developers a single place in next dev to see which cache entries (use cache functions, cached segments) are used on the current route, with HIT/MISS status, tags, and cacheLife profile.
2. Explain why a route or segment is dynamic, linking to the exact source location (e.g. "reads cookies() at app/dashboard/page.tsx:14").
3. Show revalidation events (which revalidateTag/updateTag call invalidated which entry, and from where) to make "why is this data stale?" debuggable.

Non-Goals

1. No changes to caching semantics or any public API.
2. No production overhead: instrumentation runs only in next dev.
3. Not a replacement for production logging or observability tools.

Background

Caching is one of the most common sources of confusion in the App Router. Questions like "why is this page showing stale data after revalidateTag?", "is this use cache function actually hit or re-executed every request?", and "why did this route become dynamic?" come up often, and today the answers are spread across build output, server logs, config options and trial and error.

Current alternatives and prior art:**

• Navigation Inspector** (Next.js DevTools) helps validate instant navigations with Cache Components, but does not show cache entries, tags, or lifetimes.
• React DevTools** can highlight static vs. dynamic components in dev, but not why a boundary is dynamic or what is cached inside it.
• next-cache-tools** (community) provides a tag inspection panel, but only for tags created through its own API, so it cannot see the full picture.

This proposal aims to complement these tools, not replace them.

Proposal

A new Cache Inspector panel in the existing Next.js DevTools, available only in next dev.

For the current route it lists entries like:

Entry	Kind	Status	Tags	cacheLife	Expires in
getUser(id)	use cache	HIT	user, user:123	minutes	3m 12s
getPosts()	use cache	MISS (first run)	posts	hours	59m
/dashboard segment	route	Dynamic	–	–	–

Selecting an entry shows its source location (clickable to open in editor), the reason it is dynamic when applicable, its revalidation history, and a dev-only "Invalidate" button.

Incremental scope:

1. Phase 1 (read-only): list use cache entries on the current route with HIT/MISS, tags and cacheLife.
2. Phase 2: reasons for dynamic rendering, linked to source.
3. Phase 3: revalidation event log and manual invalidate action.

Phase 1 alone would already answer the most frequent questions.

Open questions:

• Does the dev server already track enough metadata (tags, lifetime, hit/miss) to expose this cheaply, or would new instrumentation be needed?
• Should it live only in the DevTools panel, or also be exposed as data so other tools can consume it?
• Should it be gated behind Cache Components, like Navigation Inspector?

I'd be happy to work on Phase 1 if the team thinks this direction makes sense, and to adjust the design based on feedback before writing code.

[wahyuarizeina]

This is a useful direction, and Phase 1 in particular is well scoped. Being able to answer "is this use cache function actually hit?" in next dev would remove a lot of trial and error. Some thoughts on the open questions and on the harder parts of the later phases.

Open questions

1. Does the dev server already track enough metadata?
Probably enough for HIT/MISS and tags, but I'd check three things before committing to Phase 1:

• Whether hit/miss is recorded at the point where the cache handler is called, or inside the use cache wrapper. If it's the latter, an entry served from a custom cacheHandlers implementation might be reported as a MISS even when the handler returned data.
• Whether cacheLife profile values (stale, revalidate, expire) are kept as resolved values or only as the profile name. The "Expires in" column needs the resolved numbers, and a profile can contain more than one timing.
• Whether entries are keyed in a way that gives a stable identity for getUser(id) across requests. Otherwise the table will show many rows for the same function.

2. Should it be data, not just a panel?
Yes, I'd expose the data through a dev-only endpoint or a serializable event stream. That lets the panel be built on top of it, lets tests assert on cache behavior, and lets people write their own inspectors. It also makes the Phase 1 output easy to snapshot in e2e tests.

3. Should it be gated behind Cache Components?
Consider gating on whether use cache is in use, not on the Cache Components flag itself. Projects using only unstable_cache or segment-level caching would otherwise get no panel. The Navigation Inspector gating is a reasonable precedent, but it's worth checking whether the cache entries in question exist in both modes.

Phase 2: reasons for dynamic rendering

This is the hardest part, and the phrase "linking to the exact source location" needs a clear definition. A route is usually dynamic for several reasons at once: cookies(), headers(), searchParams, an uncached fetch, or an explicit connection() call. Suggested approach:

• Report the first dynamic API the render touched, in call order, with its source location.
• Keep a list of all dynamic APIs hit, not just the first, since fixing only the first often reveals the next.
• Be explicit that the reason is "first observed during this render", because a segment that isn't rendered on a given request won't report anything.

Source locations need source maps in the dev server, and they can be wrong after compilation or inside shared packages. Treat them as best-effort and show the module path as a fallback.

Phase 3: revalidation log and Invalidate button

Two concerns:

• The Invalidate button should be restricted to the dev server origin and to the same process that serves the page. Even in dev, a cross-origin page should not be able to trigger invalidation. A simple origin check and a per-session token would cover it.
• The revalidation log should record the call site of revalidateTag / updateTag if possible, because "which call invalidated this entry" is the question people actually ask. Stack traces in dev are cheap to capture, but they can be noisy, so consider capturing them only on demand.

Smaller notes

• Keep parity between Turbopack and webpack. If the inspector only works under one bundler, it will be confusing for people who switch between --turbopack and --webpack while debugging.
• For stale-while-revalidate states, the table should show more than HIT/MISS. A stale-but-served entry is a third status that matters when debugging "why is this data old?"

I'd support starting Phase 1 with the metadata checks above, then writing a short design note for Phase 2 before implementation, since the source-location part depends on details that are easier to settle on paper.