Seps to Reproduce:
When implementing a custom CacheHandler
in Next.js and the set
method is called for a full page cache (e.g., /index
), the tags
property within the ctx
argument appears to be missing. This occurs even when fetch
requests with the next: { tags: [...] }
option are present within the page component's rendering tree.
This behavior is unexpected, as the documentation suggests that tags associated with fetch
requests during the rendering process should be available to the cache handler for invalidation purposes. The absence of these tags in the ctx
for full page caches prevents custom cache handlers from effectively leveraging tag-based revalidation strategies for entire pages.
While a minimal reproduction repository would be ideal, here's a general outline of how to observe this issue:
-
Implement a custom
CacheHandler
in yournext.config.js
file. -
Within a page component (e.g.,
pages/index.js
orapp/page.js
), make one or morefetch
requests with thenext: { tags: [...] }
option. For example:// app/page.tsx (or similar in app directory) async function getData() { const res = await fetch("/api/data", { cache: "force-cache", next: { tags: ["my-data-tag", "home-page"] }, }); // ... } export default async function Home() { const data = await getData(); // ... return <div>{/* ... */}</div>; }
-
In your custom
CacheHandler
'sset
method, log or inspect thectx
argument when the key corresponds to a full page cache (e.g., the key might resemble the route path or a hash thereof).// cache-handler.js const myCacheHandler = { async get(key, ctx) { // ... your get logic }, async set(key, value, ctx) { console.log("Cache SET context for key:", key, ctx); // Observe the ctx object // ... your set logic }, async revalidateTag(tag, ctx) { // ... your revalidateTag logic }, };
// next.config.js module.exports = { cacheHandler: require.resolve("./cache-handler.js"), cacheMaxMemorySize: 0, // disable default in-memory caching };
-
Build and run your Next.js application in a production-like environment (using
next build
andnext start
). -
Access the page (e.g.,
/
). Observe the logs from your customCacheHandler
'sset
method. You will likely find that thetags
property in thectx
is missing or undefined for the full page cache entry, even though thefetch
request within the page had tags.
Expected Behavior:
The ctx
argument in the set
method of a custom CacheHandler
for full page caches should include the tags
associated with any fetch
requests made with the next: { tags: [...] }
option during the server-side rendering or Server Components rendering of that page. This would allow custom cache handlers to store and utilize these tags for future revalidation.
Current Behavior:
The tags
property in the ctx
argument of the set
method is missing (or undefined) for full page cache entries, despite the presence of tagged fetch
requests in the page component tree.