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:

DataExample policy
Immutable documentation revisionLong lifetime plus a content tag
Frequently edited public indexShorter lifetime plus a tag
Dashboard draftRequest-time or private cache
User/session dataPrivate 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:

  1. What inputs affect the result?
  2. Can two users share the result?
  3. What is the acceptable stale window?
  4. Which mutation invalidates it?
  5. How can a test prove freshness after that mutation?

References

Agent access

Choose a representation.

Published content only
Human pageYou are reading the human-facing canonical page.
Current page

Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.