Cache Revalidation Options

[silvertech-daniel]

We need to be able to optionally expire/revalidate tags without immediately removing the stale responses, just like how time-based revalidation works.

Even with the canary dynamicIO/"use cache" api, I do not see a way to implement stale-while-revalidate caching using tags. Currently revalidateTag(tag)/unstable_expireTag(...tags) completely purges the cache of entries that have those tags. These functions should optionally integrate with staleness configuration and optionally override as well, so that the cached functions may return stale results while they revalidate in the background.

Here's an example of something simply not possible to implement in a way that integrates properly with the data cache. It's simplified but directly mirrors how a Sanity CMS query function that integrates with their live content api has to work:

import type { QueryParameters, QueryResult } from '@/loading/types'
import { client } from '../client'
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

async function sanityFetch<Q extends string>({
	query,
	params
}: {
	query: Q
	params?: QueryParameters<Q>
}) {
	'use cache'

	cacheLife({
		stale: Infinity,
		revalidate: Infinity,
		expire: Infinity
	})

	const {
		result,
		syncTags
	} = await enqueue(() =>
		client.fetch<QueryResult<Q>>(query, params ?? {}, {
			filterResponse: false,
			next: {
				revalidate: process.env.NODE_ENV === 'production' ? false : undefined
			}
		})
	)

	const tags = syncTags?.map(tag => `sanity:${tag}` as const)
	if (tags) cacheTag(...tags)

	return result
}

The attempted behavior is to allow stale responses forever, and only mark responses as stale when I call expireTag() later on. The first thing to notice is that the tags can only be marked after the request is made, which is only possible with "use cache" + cacheTag() on canary. Even this canary api does not respect the infinite stale cache life. Once I call expireTag(), all pages with the affected queries block until fresh responses return. Another thing to note is that I have to call expireTag() in a route handler because there is no control of whether or not calling it within a server action can skip a router refresh. Ideally, the router would only refresh if the client-side cache was affected by the invalidated tags and those affected cached functions fully revalidated. The only work-around available is to use a route handler to sneak around Next's cache tracking.

My opinion right now is that the ideal behavior takes this even further and allows for any page to optionally have an instant stale response from the full route cache that seamlessly reconciles via RSC / router refresh once background revalidation completes for each expired cached function. For revalidated data used in suspense boundaries, it would be ideal to optionally have the old data available for the placeholder (as a parameter to a placeholder component) and have the fresh version come in via the normal html stream or possibly be awaited for fully static rendering.

[CoderDeltaLAN]

Short answer
Yes. Use cache tags and revalidateTag() for on-demand soft invalidation. It marks entries as stale but keeps serving the last response until the path is visited again and fresh data is written.

---

Minimal setup

Tag your cached fetches:

// any Server Component / Route Handler
const res = await fetch('https://api.example.com/posts', {
  next: { tags: ['posts'] }, // cache tag
  // cache: 'force-cache' // default on the server
})
const posts = await res.json()

Invalidate on demand (webhook, Server Action, or Route Handler):

// app/api/revalidate/posts/route.ts
import { revalidateTag } from 'next/cache'

export async function POST() {
  revalidateTag('posts')        // mark as stale
  return new Response('ok')
}

Behavior: revalidateTag('posts') does not delete the cached response immediately. It turns it stale; the next request to any page using that tag will refetch and overwrite the cache. Until then, users still get the previous response. This matches the “expire but don’t drop instantly” requirement.

---

Optional: background warm-up

If you want to avoid a user paying the first refetch cost, you can pre-warm after invalidating:

export async function POST() {
  revalidateTag('posts')
  // fire-and-forget warm-up (no await)
  fetch('https://your-site.com/blog', { cache: 'no-store' }).catch(() => {})
  return new Response('ok')
}

Or call the same data endpoint that your page uses to ensure the tag is re-populated.

---

Path vs tag

• revalidateTag('posts') → invalidate all cache entries that were tagged, across pages.
• revalidatePath('/blog') → invalidate only that route; useful when the path aggregates many tags.

You can combine both if needed (e.g., mutate → revalidateTag data + revalidatePath listing).

---

With unstable_cache (fine control)

import { unstable_cache } from 'next/cache'

const getPosts = unstable_cache(
  async () => (await fetch('https://api.example.com/posts')).json(),
  ['posts-key'],
  { tags: ['posts'], revalidate: false }  // keep until on-demand invalidation
)

revalidate: false keeps entries until you call revalidateTag('posts').

---

Docs

• revalidateTag: https://nextjs.org/docs/app/api-reference/functions/revalidateTag
• revalidatePath: https://nextjs.org/docs/app/api-reference/functions/revalidatePath
• Caching & Revalidating: https://nextjs.org/docs/app/guides/caching
• fetch with tags: https://nextjs.org/docs/app/api-reference/functions/fetch
• ISR guide: https://nextjs.org/docs/app/guides/incremental-static-regeneration

If this helps, please Mark as answer so others can find it.