{"id":29,"type":"docs","title":"Next.js 16 Caching Patterns","slug":"nextjs-16-caching-patterns","canonicalUrl":"https://docs.phatysd.me/content/nextjs-16-caching-patterns","status":"published","revision":2,"publishedAt":"2026-09-19T16:34:11.292Z","updatedAt":"2026-09-19T16:34:11.292Z","hierarchyPath":"Next.js > App Router > Caching","topics":["Next.js 16","Caching","Cache Components","Data freshness"],"tags":["nextjs","cache","cache-components","revalidation","performance"],"related":[{"slug":"nextjs-16-agent-first-guide","title":"Next.js 16 for Agents: A Verifiable, Production-Ready App Router Guide","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/nextjs-16-agent-first-guide"},{"slug":"what-i-learned-writing-nextjs-guide-agents","title":"What I Learned from Writing a Next.js Guide for Agents","type":"blog","canonicalUrl":"https://docs.phatysd.me/content/what-i-learned-writing-nextjs-guide-agents"}],"body":"# Next.js 16 Caching Patterns\n\nCaching 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.\n\n## Cache Components are opt-in\n\nWhen using the current Cache Components model, enable it explicitly:\n\n```ts\n// next.config.ts\nimport type { NextConfig } from \"next\"\n\nconst nextConfig: NextConfig = {\n  cacheComponents: true,\n}\n\nexport default nextConfig\n```\n\nThe 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.\n\n## Cache a public query\n\n```ts\nimport { cacheLife, cacheTag } from \"next/cache\"\n\nexport async function getPublicArticle(slug: string) {\n  \"use cache\"\n  cacheLife(\"hours\")\n  cacheTag(`content:${slug}`)\n\n  return getPublishedItemBySlug(slug)\n}\n```\n\nOnly 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.\n\n## Time-based policy\n\nUse `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:\n\n| Data | Example policy |\n| --- | --- |\n| Immutable documentation revision | Long lifetime plus a content tag |\n| Frequently edited public index | Shorter lifetime plus a tag |\n| Dashboard draft | Request-time or private cache |\n| User/session data | Private cache or no shared cache |\n\nDo not choose a long lifetime without an invalidation path. A fast wrong answer is still wrong.\n\n## On-demand invalidation\n\n`cacheTag()` associates cached work with a tag. After a publish or revision mutation:\n\n- Use `updateTag()` in a Server Action when the author must immediately see the write.\n- Use `revalidateTag(tag, profile)` when stale-while-revalidate behavior is acceptable.\n- Use `revalidatePath(path)` when a known route must be refreshed.\n\n```ts\n\"use server\"\n\nimport { updateTag } from \"next/cache\"\n\nexport async function publishArticle(input: FormData) {\n  await requireOwner()\n  const item = await publishInTransaction(input)\n\n  updateTag(`content:${item.slug}`)\n  updateTag(\"content:index\")\n  return { id: item.id, revision: item.revisionNumber }\n}\n```\n\nThe invalidation call belongs beside the mutation. Do not leave it to the page that happens to be open after publishing.\n\n## Suspense and dynamic work\n\nWhen 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.\n\n## Agent checklist\n\nBefore changing caching, answer:\n\n1. What inputs affect the result?\n2. Can two users share the result?\n3. What is the acceptable stale window?\n4. Which mutation invalidates it?\n5. How can a test prove freshness after that mutation?\n\n## References\n\n- [Next.js caching](https://nextjs.org/docs/app/building-your-application/caching)\n- [`use cache`](https://nextjs.org/docs/app/api-reference/directives/use-cache)\n- [`cacheLife`](https://nextjs.org/docs/app/api-reference/functions/cacheLife)\n- [`cacheTag`](https://nextjs.org/docs/app/api-reference/functions/cacheTag)\n- [`revalidateTag`](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)\n- [`updateTag`](https://nextjs.org/docs/app/api-reference/functions/updateTag)\n- [Cache Components migration](https://nextjs.org/docs/app/guides/migrating-to-cache-components)\n"}