Docs · Next.js / App Router / Caching
Next.js 16 Caching Patterns
Next.js 16 Caching Patterns
Caching is a data-lifecycle decision, not a decoration added after a page is slow. For every query, an agent should know whether data is request-time, prerendered, shared, private, time-revalidated, or invalidated by a mutation.
Cache Components are opt-in
When using the current Cache Components model, enable it explicitly:
// next.config.ts
import type { NextConfig } from "next"
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
The current web-blog repository does not enable cacheComponents in its deployed configuration. Do not add it as a drive-by change: first map every request-time data source, loading state, and deployment cache handler.
Cache a public query
import { cacheLife, cacheTag } from "next/cache"
export async function getPublicArticle(slug: string) {
"use cache"
cacheLife("hours")
cacheTag(`content:${slug}`)
return getPublishedItemBySlug(slug)
}
Only cache data that is safe to share. A query that depends on cookies, authorization, or a user ID must not enter a shared public cache accidentally.
Time-based policy
Use cacheLife() to express freshness. Named profiles make the policy readable; custom profiles can define stale, revalidate, and expire windows. Choose a lifetime based on content behavior:
| Data | Example policy |
|---|---|
| Immutable documentation revision | Long lifetime plus a content tag |
| Frequently edited public index | Shorter lifetime plus a tag |
| Dashboard draft | Request-time or private cache |
| User/session data | Private cache or no shared cache |
Do not choose a long lifetime without an invalidation path. A fast wrong answer is still wrong.
On-demand invalidation
cacheTag() associates cached work with a tag. After a publish or revision mutation:
- Use
updateTag()in a Server Action when the author must immediately see the write. - Use
revalidateTag(tag, profile)when stale-while-revalidate behavior is acceptable. - Use
revalidatePath(path)when a known route must be refreshed.
"use server"
import { updateTag } from "next/cache"
export async function publishArticle(input: FormData) {
await requireOwner()
const item = await publishInTransaction(input)
updateTag(`content:${item.slug}`)
updateTag("content:index")
return { id: item.id, revision: item.revisionNumber }
}
The invalidation call belongs beside the mutation. Do not leave it to the page that happens to be open after publishing.
Suspense and dynamic work
When a page combines cached public content with request-time or user-specific content, isolate the dynamic part behind Suspense and a meaningful loading UI. This keeps the static portion useful while the request-time portion resolves.
Agent checklist
Before changing caching, answer:
- What inputs affect the result?
- Can two users share the result?
- What is the acceptable stale window?
- Which mutation invalidates it?
- How can a test prove freshness after that mutation?
References
Agent access
Choose a representation.
Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.