next-v16

スキル：next-v16

Next.js 16 App Router（2025年10月 GA）。学習データよりも、node_modules/next/dist/docs/ にあるバージョンに対応したドキュメントを優先してください。Codemod：npx @next/codemod@canary upgrade latest、middleware-to-proxy、next-async-request-api。

対象範囲

• 対象：Next.js 16 App Router — Turbopack、Cache Components と従来のキャッシュモデル、proxy.ts、非同期リクエスト API、Server Components、Server Actions、ストリーミング、メタデータ、クライアントアイランド
• 対象外：Pages Router、汎用的な React 19（vercel-react を参照）、Next.js 以外のサーバーレンダリング

前提

• Next.js 16.x、React 19.2 App Router、Node.js 20.9 以上、TypeScript 5.1 以上
• キャッシュモデルは 2 種類あります。API を選ぶ前に、next.config の cacheComponents を確認してください
• どちらのモデルでも、fetch はデフォルトでキャッシュされません。明示的に有効化してください

原則

• Next.js API を生成する前に、この環境にインストールされたバージョンの node_modules/next/dist/docs/ を参照してください
• キャッシュはオプトインです。サーバー側の fetch ごとに意図を宣言してください
• ネットワーク境界は proxy.ts（Node.js）です。認証ゲート、リライト、リダイレクト、ヘッダーの変更を行います
• リクエスト API は非同期です：await cookies()、await headers()、await draftMode()、await params、await searchParams
• デフォルトのバンドラーは Turbopack です。--webpack はオプトアウトであり、16 での標準的な書き方ではありません
• Server Components を優先してください。操作が必要なリーフコンポーネントに 'use client' を配置してください
• ユーザーから Next.js コードの監査または最新化を依頼された場合は、references/_review-algorithm.md に従ってください

制約

MUST

• params、searchParams、cookies()、headers()、draftMode() を await してください
• revalidateTag(tag, profile) は cacheLife プロファイル（'max' | 'hours' | 'days' | インラインの { expire }）を指定して呼び出してください。引数 1 つの形式は非推奨です
• ユーザーが書き込みを直ちに確認する必要がある場合（read-your-writes）は、Server Actions から updateTag(tag) を使用してください。stale-while-revalidate には revalidateTag(tag, 'max') を使用してください
• proxy.ts から proxy をエクスポートしてください（名前付きまたはデフォルト）。ランタイムは nodejs で、Edge には設定できません
• 'use cache'、cacheLife、または cacheTag を追加する前に、cacheComponents: true であることを確認してください

SHOULD

• Cache Components は明示的な移行としてのみ有効にしてください。cacheComponents: true を設定してから、セグメント設定の dynamic / revalidate / fetchCache を 'use cache' と cacheLife に置き換えてください。ガイド：Cache Components への移行
• アプリで experimental.dynamicIO / experimental.useCache / experimental.ppr を採用していなかった場合は、これらのフラグを削除してください。単なる改名として cacheComponents: true を設定しないでください。Suspense の外にある未キャッシュデータが原因でビルドに失敗することがあります
• Cache Components を使用しない場合は、cache: 'force-cache'、next: { revalidate, tags }、または unstable_cache でキャッシュしてください。ガイド：Cache Components を使用しないキャッシュ
• proxy.ts に /_next/static、/_next/image、公開アセットを除外する config.matcher を設定してください
• next/image の remotePatterns を使用してください（非推奨の images.domains は使用しないでください）。next/legacy/image ではなく next/image を使用してください
• サイトマップと robots ファイルは app/sitemap.ts と app/robots.ts から生成してください
• cacheLife / cacheTag は next/cache（安定版）からインポートしてください。unstable_cacheLife / unstable_cacheTag は使用しないでください
• skipMiddlewareUrlNormalize を skipProxyUrlNormalize に名前変更してください

避けること

• cacheComponents: true が設定されていないアプリで 'use cache' を生成すること（このディレクティブは Cache Components の機能です）
• experimental.dynamicIO／experimental.useCache／experimental.ppr が設定されていたことを理由に、cacheComponents: true に切り替えること。このフラグを有効にするのは、プログラミングモデルの移行です
• 新しいコードで middleware.ts を使うこと。Edge ランタイムが引き続き必要な場合に限り、既存のものを残してください。これは非推奨です
• 同期版の params／cookies()／headers()（警告なしで削除されています）
• next lint（削除されています）。ESLint または Biome で lint を実行してください
• experimental.ppr、experimental.dynamicIO、experimental.useCache、export const experimental_ppr（削除されています）
• experimental.turbopack（トップレベルの turbopack に移動しました）
• experimental.turbo.persistentCaching — これは Next 16 の API ではありません。ファイルシステムキャッシュには experimental.turbopackFileSystemCacheForDev／experimental.turbopackFileSystemCacheForBuild を使います（デフォルトで有効です）
• Next 16 の慣用的な使い方として next dev --turbopack／next build --turbopack を使うこと。Turbopack はすでにデフォルトです。オプトアウトするには --webpack を使います
• デフォルトの next build の実行時に、設定でカスタム webpack を使うこと（失敗します）。Turbopack に移行するか、--webpack を渡してください
• revalidateTag の 'max' を「書き込み直後の読み取り」と見なすこと。これは SWR です。Server Actions では updateTag を使ってください
• すべての Route Handler を Server Actions に置き換える必要があると主張すること。Cookie、Webhook、OAuth コールバック、外部 API のプロキシには、引き続き Route Handler が適しています

インタラクション

• React 19 の並行 UI：vercel-react
• ハイドレーション後のクライアントデータ：tanstack-query-v5
• Next サーバー上で完結するフォーム：workflow/form

2 つのキャッシュモデル（混在させないでください）

設定	生成する内容
cacheComponents が未設定／false	旧モデルです。cache: 'force-cache' または next.revalidate を指定しない限り、fetch はキャッシュされません。セグメント設定の dynamic、revalidate、fetchCache は引き続き機能します。fetch 以外には unstable_cache を使います。'use cache' は出力しないでください
cacheComponents: true	Cache Components です。デフォルトでは動的です。'use cache' と cacheLife／cacheTag でキャッシュします。セグメント設定の dynamic／revalidate／fetchCache はエラーになります。PPR はデフォルトの動作です。'use cache' スコープ内のフェッチはキャッシュされます

'use cache' には cacheComponents: true が必要です（use cache）。このフラグを有効にするのは移行であり、Next 16 で自動的に有効になるわけではありません（cacheComponents）。

無効化（両モデル共通、Next 16 のシグネチャ）：

• revalidateTag(tag, 'max') — stale-while-revalidate。Server Actions と Route Handlers で使えます
• updateTag(tag) — 同じリクエスト内で有効期限を切らし、新しいデータを読み取ります。Server Actions のみ
• refresh() — キャッシュされていないデータのみを更新します。Server Actions のみ
• revalidatePath — 変更なし

Next.js 16 の慣用的な使い方（Next 15 のコードを生成しないでください）

• proxy.ts + export function proxy（Node）— Edge が必要な場合を除き、middleware.ts は使わないでください
• Turbopack がデフォルト — --turbopack を付けずに next dev／next build を実行します。オプトアウトするには --webpack を使います
• await params／await searchParams／await cookies()
• revalidateTag(tag, profile) — revalidateTag(tag) ではありません
• reactCompiler: true は安定版で、オプトイン方式です（デフォルトではありません）
• Next の設定のルートに turbopack: { ... } を指定します — experimental.turbopack ではありません
• 並列ルートのスロットには default.js が必要です（ないとビルドに失敗します）

レビューまたはリファクタリングの方法

ユーザーから Next のコードのレビュー、リファクタリング、モダナイズ、監査を依頼された場合は、references/_review-algorithm.md に従ってください。独自の判断で進めないでください。

1. モード A（約 20 ファイル以下）またはモード B（ツリー全体）を選択します
2. カテゴリ 2 の前に next.config からキャッシュモデルを判定します
3. カテゴリ単位で順に確認し、対象範囲の宣言、カテゴリごとの進捗行、カバレッジ表を提示します
4. 最後にカテゴリ 9 を実施します（重複排除／統合／削除／'use client' の適用範囲縮小）

ルールのカテゴリ

1. ビルドとバンドル — 重大 — バレル、optimizePackageImports、serverExternalPackages、Turbopack、next/dynamic
2. キャッシュ — 重大 — fetch の意図、セグメント設定 または 'use cache'（モデルによって異なります）、revalidateTag+プロファイル、revalidatePath、React cache()
3. サーバーコンポーネント — 高 — 並列フェッチ、Suspense、コロケーション、プリロード、クライアントでの初回フェッチなし
4. ルーティング — 高 — 並列ルート／インターセプトルート、プリフェッチ、proxy.ts、notFound()
5. サーバーアクション — 中〜高 — フォーム、useFormStatus、アクションの結果、楽観的 UI、再検証。ミューテーションがすでに外部 API に送信されている場合はスキップします
6. ストリーミング — 中 — Suspense、待機処理のあるルートでの loading.tsx、error.tsx、対応するスケルトン
7. メタデータ — 中 — generateMetadata、sitemap.ts、robots.ts、opengraph-image.tsx
8. クライアントアイランド — 低〜中 — リーフでの 'use client'、children スロット、ハイドレーション、next/script
9. コードベースの健全性 — 横断的 — フェッチャーの重複排除、ルートの統合、デッドコード、境界の監査、命名の不整合

ルール一覧：references/compiled.md。ルールファイル：references/。

参考資料

• Next.js 16 ブログ
• 16 へのアップグレード
• キャッシュ（Cache Components）
• Cache Components を使用しないキャッシュ
• Cache Components への移行
• use cache
• proxy.ts
• middleware → proxy