Invalidate selected data
A cached database or CMS read needs targeted invalidation after related content changes.
Next.js 16+ · Function
cacheTag
cacheTag labels cached data for selective, on-demand invalidation. Use it in a 'use cache' scope, then invalidate its tags with updateTag or revalidateTag.
- Since
- 16.0.0
How it works
Call cacheTag inside a 'use cache' scope and pass one or more string labels to associate with the cached result. Later, invalidate matching entries with updateTag when a user mutation must immediately read fresh data, or with revalidateTag when stale-while-revalidate behavior is acceptable.
Syntax
cacheTag(...tags: string[]): voidParameters
| Name | Type | Description |
|---|---|---|
tags | string[] | One or more string tags associated with the cached data. |
Returns
No return value; it associates the supplied tags with the cached data.
Key points
- It attaches invalidation labels to cached data so selected entries can be purged or revalidated later.
- Pass one or more strings as the tag values.
- The tags can be invalidated on demand from a Server Function or Route Handler.
- cacheTag became stable in Next.js 16.0.0, and the older unstable_cacheTag name was deprecated.
Common mistakes
- The cacheComponents flag must be enabled before using cacheTag.
- Each call is limited to 128 tags, and every tag can contain at most 256 characters.
- Use updateTag only from a Server Function; use revalidateTag from a Route Handler or another suitable context.
Example: Tag a cached read
import { cacheTag } from 'next/cache'
export async function getProducts() {
'use cache'
cacheTag('products')
return db.query('SELECT * FROM products')
}This cached read is labeled so a later invalidation call can target the products entry.
When to use it
Read-your-own-writes
A form or other user mutation should make the next read reflect the write immediately.
Background revalidation
A webhook, cron job, or route-triggered refresh can tolerate stale data while revalidation runs.
Interview questions
QWhat problem does cacheTag solve?
cacheTag labels cached data for selective, on-demand invalidation. It is used inside a 'use cache' scope and accepts one or more strings.
Follow-up: How would you handle a form mutation? Call updateTag from the Server Function so the next read waits for fresh data.
QWhen should updateTag and revalidateTag be used?
Use updateTag when the user should immediately see the result of their mutation. Use revalidateTag when serving stale content during background revalidation is acceptable.
Follow-up: What is the key context restriction? updateTag is limited to Server Functions, while revalidateTag can also be used from Route Handlers.
QWhen did cacheTag become stable?
cacheTag is stable in Next.js 16.0.0, replacing unstable_cacheTag without the unstable_ prefix. The current import is from next/cache.
Follow-up: What configuration accompanies it? Enable the cacheComponents flag in next.config.js.
Related
cacheComponentsuse cachecacheLifeupdateTagrevalidateTagServer FunctionsRoute Handlers