---

name: nextjs-cache-management description: Next.js App Routerのキャッシュ戦略と無効化パターン。unstable_cache, revalidateTag, updateTagの正しい使い分け。「キャッシュが古い」「データが反映されない」問題の調査・解決に使う。

Next.js Cache Management

Next.js App Router のキャッシュ問題を素早く診断・解決するスキル。

Trigger

• 「データが反映されない」「キャッシュが古い」「即座に更新されない」
• 「unstable_cache」「revalidateTag」「キャッシュ無効化」
• Server Action後にデータが古いまま

最重要: mutation後のキャッシュ無効化

これを忘れると「データ追加したのに一覧に出てこない」問題が起きる！

// ❌ 間違い: キャッシュ無効化なし
export async function addTask(data: TaskInput) {
  await db.insert(tasks).values(data);
  // キャッシュが古いまま！
}

// ✅ 正解: mutation後にupdateTag
import { updateTag } from 'next/cache';

export async function addTask(data: TaskInput) {
  await db.insert(tasks).values(data);
  updateTag('tasks');  // ← これが必須！
}

Next.js 16 のキャッシュAPI

1. unstable_cache — データ取得のキャッシュ

import { unstable_cache } from 'next/cache';

const getTasks = unstable_cache(
  async () => await db.select().from(tasks),
  ['tasks'],           // キャッシュキー
  {
    tags: ['tasks'],   // 無効化用タグ
    revalidate: 30     // 秒数（オプション）
  }
);

2. updateTag — Server Action内からの即時無効化

import { updateTag } from 'next/cache';

// Server Action内で使用
export async function addTask(data: TaskInput) {
  await db.insert(tasks).values(data);
  updateTag('tasks');  // 同一リクエスト内で即座に反映
}

特徴:

• read-your-own-writes対応（追加後すぐに一覧に反映）
• Server Action内からのみ呼び出し可能
• mutation後はこれを使う！

3. revalidateTag — 外部からの無効化

import { revalidateTag } from 'next/cache';

// Next.js 16では2引数必須
revalidateTag('tasks', 'default');

注意: Server Action内からの即時更新には updateTag を使う。

チェックリスト: キャッシュ問題の調査

1. actions.ts を確認 — mutation関数に updateTag があるか？
2. タグの一致確認 — unstable_cache の tags と updateTag の引数が一致してるか？
3. 全mutation箇所を網羅 — add/edit/delete/sync 全てに無効化があるか？

推奨パターン・修正例

キャッシュタグの一元管理パターンと実際の修正例は references/cache-tag-pattern.md を参照。

よくある間違い

間違い	正解
mutation後に updateTag を忘れる	全mutation関数に追加
タグ名のtypo	定数で一元管理
一部のmutationだけ対応	add/edit/delete/sync 全て対応
revalidateTag を Server Action内で使う	updateTag を使う

自己拡張

このスキルは自己拡張型。キャッシュ問題を解決したら LEARNINGS.md に追記。

⚠️ よくある落とし穴

• mutation後の updateTag 忘れ: これが最も多い問題。add/edit/delete だけでなく、sync系・AI系などすべてのmutation関数に updateTag を追加する。1箇所でも漏れると「追加したのに一覧に出ない」問題が起きる
• revalidateTag と updateTag の混同: Server Action内からの即時無効化は updateTag を使う。revalidateTag はServer Action内では read-your-own-writes に対応しない
• タグ名のtypo: unstable_cache の tags と updateTag の引数が1文字でも違うと無効化が効かない。CACHE_TAGS 定数で一元管理する
• Next.js 16での revalidateTag の引数変更: Next.js 16では revalidateTag('tasks', 'default') と2引数が必須。1引数で呼ぶとエラーになる