---
id: 29
type: docs
title: "Next.js 16 Caching Patterns"
slug: "nextjs-16-caching-patterns"
canonical_url: "https://docs.phatysd.me/content/nextjs-16-caching-patterns"
status: published
revision: 2
published_at: "2026-09-19T16:34:11.292Z"
updated_at: "2026-09-19T16:34:11.292Z"
hierarchy_path: "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
    canonical_url: "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
    canonical_url: "https://docs.phatysd.me/content/what-i-learned-writing-nextjs-guide-agents"
---

# 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:

```ts
// 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

```ts
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.

```ts
"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

- [Next.js caching](https://nextjs.org/docs/app/building-your-application/caching)
- [`use cache`](https://nextjs.org/docs/app/api-reference/directives/use-cache)
- [`cacheLife`](https://nextjs.org/docs/app/api-reference/functions/cacheLife)
- [`cacheTag`](https://nextjs.org/docs/app/api-reference/functions/cacheTag)
- [`revalidateTag`](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)
- [`updateTag`](https://nextjs.org/docs/app/api-reference/functions/updateTag)
- [Cache Components migration](https://nextjs.org/docs/app/guides/migrating-to-cache-components)
