fix(app-router): tag cached pages by route pattern (#923)

Cached App Router pages only carried implicit revalidatePath tags derived from the resolved URL. That left dynamic routes tagged with concrete values, so pattern-scoped invalidation like revalidatePath("/blog/[slug]", "layout") could miss entries rendered at /blog/hello.

The generated RSC entry now delegates implicit tag construction to a typed helper that combines exact pathname tags with route-segment-derived layout, page, and route handler tags. Focused tests cover dynamic route patterns, route groups, root aliases, and route handler leaves.

Refs #921

Author: NathanDrake2406

knip.ts

@@ -70,8 +70,8 @@ export default {
     // probed via require.resolve
     "next-intl",
 
-    // vitest reporter
-    "agent",
+    // vitest reporter used outside CI
+    ...(process.env.CI ? [] : ["agent"]),
 
     // internal module name, not an actual dependency
     "private-next-instrumentation-client",

packages/vinext/src/entries/app-rsc-entry.ts

@@ -57,6 +57,7 @@ const appRouteHandlerCachePath = resolveEntryPath(
   "../server/app-route-handler-cache.js",
   import.meta.url,
 );
+const implicitTagsPath = resolveEntryPath("../server/implicit-tags.js", import.meta.url);
 const appPageCachePath = resolveEntryPath("../server/app-page-cache.js", import.meta.url);
 const appPageExecutionPath = resolveEntryPath("../server/app-page-execution.js", import.meta.url);
 const appPageBoundaryRenderPath = resolveEntryPath(
@@ -437,6 +438,7 @@ import {
 import {
   applyRouteHandlerMiddlewareContext as __applyRouteHandlerMiddlewareContext,
 } from ${JSON.stringify(appRouteHandlerResponsePath)};
+import { buildPageCacheTags } from ${JSON.stringify(implicitTagsPath)};
 import { _consumeRequestScopedCacheLife, getCacheHandler } from "next/cache";
 import { getRequestExecutionContext as _getRequestExecutionContext } from ${JSON.stringify(requestContextShimPath)};
 import { setRootParams as __setRootParams, pickRootParams as __pickRootParams } from ${JSON.stringify(rootParamsShimPath)};
@@ -502,27 +504,6 @@ async function __isrSet(key, data, revalidateSeconds, tags) {
   const handler = getCacheHandler();
   await handler.set(key, data, { revalidate: revalidateSeconds, tags: Array.isArray(tags) ? tags : [] });
 }
-function __pageCacheTags(pathname, extraTags) {
-  const tags = [pathname, "_N_T_" + pathname];
-  // Layout hierarchy tags — matches Next.js getDerivedTags.
-  tags.push("_N_T_/layout");
-  const segments = pathname.split("/");
-  let built = "";
-  for (let i = 1; i < segments.length; i++) {
-    if (segments[i]) {
-      built += "/" + segments[i];
-      tags.push("_N_T_" + built + "/layout");
-    }
-  }
-  // Leaf page tag — revalidatePath(path, "page") targets this.
-  tags.push("_N_T_" + built + "/page");
-  if (Array.isArray(extraTags)) {
-    for (const tag of extraTags) {
-      if (!tags.includes(tag)) tags.push(tag);
-    }
-  }
-  return tags;
-}
 // Note: cache entries are written with \`headers: undefined\`. Next.js stores
 // response headers (e.g. set-cookie from cookies().set() during render) in the
 // cache entry so they can be replayed on HIT. We don't do this because:
@@ -2122,7 +2103,9 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
   }
 
   const { route, params } = match;
-  setCurrentFetchSoftTags(__pageCacheTags(cleanPathname, []));
+  setCurrentFetchSoftTags(
+    buildPageCacheTags(cleanPathname, [], route.routeSegments, route.routeHandler ? "route" : "page"),
+  );
 
   // Update navigation context with matched params
   setNavigationContext({
@@ -2137,6 +2120,9 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
     const handler = route.routeHandler;
     const method = request.method.toUpperCase();
     const revalidateSeconds = __getAppRouteHandlerRevalidateSeconds(handler);
+    const __buildRouteHandlerPageCacheTags = function(pathname, extraTags) {
+      return buildPageCacheTags(pathname, extraTags, route.routeSegments, "route");
+    };
     if (__hasAppRouteHandlerDefaultExport(handler) && process.env.NODE_ENV === "development") {
       console.error(
         "[vinext] Detected default export in route handler " + route.pattern + ". Export a named export for each HTTP method instead.",
@@ -2179,7 +2165,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
     ) {
       const __cachedRouteResponse = await __readAppRouteHandlerCacheResponse({
         basePath: __basePath,
-        buildPageCacheTags: __pageCacheTags,
+        buildPageCacheTags: __buildRouteHandlerPageCacheTags,
         cleanPathname,
         clearRequestContext: function() {
           __clearRequestContext();
@@ -2209,7 +2195,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
           });
           await _runWithUnifiedCtx(__revalUCtx, async () => {
             _ensureFetchPatch();
-            setCurrentFetchSoftTags(__pageCacheTags(cleanPathname, []));
+            setCurrentFetchSoftTags(buildPageCacheTags(cleanPathname, [], route.routeSegments, "route"));
             await renderFn();
           });
         },
@@ -2224,7 +2210,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
     if (typeof handlerFn === "function") {
       return __executeAppRouteHandler({
         basePath: __basePath,
-        buildPageCacheTags: __pageCacheTags,
+        buildPageCacheTags: __buildRouteHandlerPageCacheTags,
         cleanPathname,
         clearRequestContext: function() {
           __clearRequestContext();
@@ -2370,7 +2356,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
         });
         return _runWithUnifiedCtx(__revalUCtx, async () => {
           _ensureFetchPatch();
-          setCurrentFetchSoftTags(__pageCacheTags(cleanPathname, []));
+          setCurrentFetchSoftTags(buildPageCacheTags(cleanPathname, [], route.routeSegments, "page"));
           setNavigationContext({ pathname: cleanPathname, searchParams: new URLSearchParams(), params });
           // Slot context (X-Vinext-Mounted-Slots) is inherited from the
           // triggering request so the regen result is cached under the
@@ -2400,7 +2386,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
           __clearRequestContext();
           const __freshHtml = await __readAppPageTextStream(__revalHtmlStream);
           const __freshRscData = await __revalRscCapture.capturedRscDataPromise;
-          const __pageTags = __pageCacheTags(cleanPathname, getCollectedFetchTags());
+          const __pageTags = buildPageCacheTags(cleanPathname, getCollectedFetchTags(), route.routeSegments, "page");
           return { html: __freshHtml, rscData: __freshRscData, tags: __pageTags };
         });
       },
@@ -2565,7 +2551,7 @@ async function _handleRequest(request, __reqCtx, _mwCtx) {
     getFontStyles: _getSSRFontStyles,
     getNavigationContext: _getNavigationContext,
     getPageTags() {
-      return __pageCacheTags(cleanPathname, getCollectedFetchTags());
+      return buildPageCacheTags(cleanPathname, getCollectedFetchTags(), route.routeSegments, "page");
     },
     getRequestCacheLife() {
       return _consumeRequestScopedCacheLife();

packages/vinext/src/server/implicit-tags.ts

@@ -0,0 +1,62 @@
+const NEXT_CACHE_IMPLICIT_TAG_ID = "_N_T_";
+
+type AppCacheLeafKind = "page" | "route";
+
+function appendUnique(tags: string[], tag: string): void {
+  if (!tags.includes(tag)) tags.push(tag);
+}
+
+// App route segments come from raw filesystem directories, so dynamic
+// segments are already in bracket notation such as [slug] or [...all].
+function normalizeRouteSegment(segment: string): string | null {
+  if (!segment || segment === "." || segment.startsWith("@")) return null;
+  return segment;
+}
+
+function buildRouteCachePath(routeSegments: string[], leafKind: AppCacheLeafKind): string {
+  const parts: string[] = [];
+  for (const segment of routeSegments) {
+    const normalized = normalizeRouteSegment(segment);
+    if (normalized) parts.push(normalized);
+  }
+  parts.push(leafKind);
+  return `/${parts.join("/")}`;
+}
+
+function appendDerivedTags(tags: string[], routePath: string): void {
+  appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}/layout`);
+
+  if (!routePath.startsWith("/")) return;
+
+  const routeParts = routePath.split("/");
+  const leafIndex = routeParts.length - 1;
+  for (let i = 1; i <= routeParts.length; i++) {
+    let currentPathname = routeParts.slice(0, i).join("/");
+    if (!currentPathname) continue;
+
+    const isLeaf = i - 1 === leafIndex;
+    if (!isLeaf) {
+      currentPathname = `${currentPathname}/layout`;
+    }
+
+    appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}${currentPathname}`);
+  }
+}
+
+export function buildPageCacheTags(
+  pathname: string,
+  extraTags: string[],
+  routeSegments: string[],
+  leafKind: AppCacheLeafKind,
+): string[] {
+  const tags = [pathname, `${NEXT_CACHE_IMPLICIT_TAG_ID}${pathname}`];
+  if (pathname === "/") appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}/index`);
+  if (pathname === "/index") appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}/`);
+  appendDerivedTags(tags, buildRouteCachePath(routeSegments, leafKind));
+
+  for (const tag of extraTags) {
+    appendUnique(tags, tag);
+  }
+
+  return tags;
+}