nextjs

Next.js 16 App Router のベストプラクティス

AI エージェント向けの包括的な Next.js 16 App Router ガイドです。9 カテゴリーにわたる45のルールを収録し、重要度の高いもの（ビルドの最適化、キャッシュ戦略）から、コードベース全体に関わる衛生管理（重複排除、不要なルート、境界の一貫性）まで、影響度順に優先順位を付けています。'use cache' ディレクティブによる暗黙的なキャッシュの置き換え、revalidateTag(tag, cacheLife) の要件、middleware.ts に代わる proxy.ts、Turbopack の永続キャッシュ、App Router の規約など、Next.js 16 の変更を反映しています。

ルールファイルでは パターンの形（API 名ではありません）を説明し、冒頭に 「認識すべき形」 セクションを設けています。同じ問題が取りうる構文上の別の形を2〜4個挙げています。特に価値の高いルール（実際によく見られる別の形があるもの — 'use cache'、並列フェッチ、動的インポート、Server Action フォーム、クライアント境界、サーバーとクライアントのフェッチ方法）には、grep で見つけやすいケース以外のパターン検出を学べるよう、具体的な 「別の形」 の誤った例と正しい例のペアも追加しています。

適用する場面

• 新しい Next.js 16 App Router コードを書くとき
• Next.js コードベースを監査または最新化するとき — 単一ファイル、PR、リポジトリ全体（references/_review-algorithm.md を参照）
• Next.js 15 から16へ移行するとき（暗黙的なキャッシュ → 'use cache'、middleware.ts → proxy.ts、引数1つの revalidateTag → cacheLife 付き）
• 'use cache'、unstable_cache、revalidateTag、revalidatePath を使ったキャッシュ戦略を設定するとき
• Server Components と、並列または同居させたデータフェッチを実装するとき
• 並列ルート、インターセプトルート、プリフェッチ、proxy.ts を設定するとき
• フォーム処理やデータ変更のために Server Actions を作成するとき
• 'use client' 境界を調整して、クライアントバンドルを最小化するとき
• 単一ファイルのルールでは検出できないコードベースレベルの問題を見つけるとき：重複したサーバーフェッチャー、ほぼ同じルートやレイアウト、不要なルート、ルートツリー全体への 'use client' の伝播、プロパティ形状の不整合（カテゴリー9を参照）

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

ユーザーから Next.js コードのレビュー、リファクタリング、最新化、監査を依頼された場合（単一ファイルでもリポジトリ全体でも）、references/_review-algorithm.md に従ってください。独自の判断で進めないでください。

このドキュメントにある、必ず守るべき4つの事項：

1. 2つのモード — リポジトリ全体の監査を決して断らないでください。 モードA（範囲を限定、約20ファイル以下）か モードB（ツリー全体：一覧作成のパス + 対象を絞った確認 + カテゴリー9全体）を選びます。
2. grep より判断を重視します。 各ルールが示すのは構文上の目印ではなく、パターンの形です。確認を始める前に各ルールの 「認識すべき形」 セクションを読みます。grep では見つけやすい違反を検出できても、価値の高い違反を見逃します（ボタン1つのために 'use client' が付いたレイアウト、初期ページデータを取得する TanStack Query、Server Action の役割を担うルートハンドラー、'use cache' を模した独自のキャッシュレイヤー、親子の Server Components にまたがって隠れている逐次フェッチなど）。
3. ファイルごとではなくカテゴリーごとに確認し、確認漏れを防ぐ仕組みを設けます。 優先順位（CRITICAL → … → CROSS-CUTTING）に従い、対象の全ファイルをカテゴリーごとに確認します。アルゴリズムでは、対象範囲の宣言、カテゴリーごとの進捗行、最後の 網羅状況テーブル（カテゴリー × ファイル／分類、セルの値は {clean, N findings, n/a}）が必須です。出力にカテゴリーが欠けていれば、すぐにわかります。
4. コードベースレベルの指摘はカテゴリー9で行います。 単一ファイルのルールでは、「この2つのルートは1つにまとめるべき」や「この Server Action は使われていない」といったことは判断できません。最後にカテゴリー9（コードベースの衛生管理）で一覧全体を確認し、削除／重複排除／再利用／統合に関する指摘をまとめます。

単一ファイルについての個別の質問（「このキャッシュ戦略は適切ですか？」など）は、該当するルールを直接参照してください。このアルゴリズムは複数ファイルやリポジトリ全体を対象とする場合に使います。

ルールカテゴリ

#	カテゴリ	影響度	ルール数	主なトピック
1	ビルドとバンドルの最適化	重大	5	Turbopack、optimizePackageImports、動的インポート、バレルファイル、serverExternalPackages
2	キャッシュ戦略	重大	6	'use cache'、revalidateTag+cacheLife、fetch オプション、セグメント設定
3	サーバーコンポーネントとデータ取得	高	6	並列取得、ストリーミング、コロケーション、プリロード、クライアントでの取得禁止、エラー処理
4	ルーティングとナビゲーション	高	5	並列ルート、インターセプトルート、プリフェッチ、proxy.ts、notFound()
5	サーバーアクションとミューテーション	中〜高	5	サーバーアクション、useFormStatus、アクション結果のエラー、useOptimistic、再検証
6	ストリーミングと読み込み状態	中	5	Suspense の配置、loading.tsx、error.tsx、スケルトンの一致、ネストされた Suspense
7	メタデータと SEO	中	4	generateMetadata、sitemap.ts、robots.ts、opengraph-image.tsx
8	クライアントコンポーネント	低〜中	4	'use client' 境界、children パターン、ハイドレーションの不一致、next/script
9	コードベースの整理	低〜中	5	サーバー側 fetcher の重複排除、ルートの統合、未使用ルート／アクション、'use client' の伝播、props のずれ

クイックリファレンス

重要なパターン — まずこれらを正しく設定してください：

• 結果をキャッシュする Server Component／関数には 'use cache' を追加します（Next.js 16 では暗黙的な fetch キャッシュが廃止されました）
• プロファイルを指定して revalidateTag(tag, cacheLife) を呼び出します — 引数を1つだけ渡す API は使わないでください
• フラットなエクスポート構造を持つアイコン／ユーティリティライブラリには optimizePackageImports を設定します
• Turbopack の永続キャッシュを無効にしないでください
• /api/... への POST ではなく、<form action={serverAction}> でラップします

Next.js 16 の慣用表現（Next.js 15 のパターンを生成しないでください）：

• proxy.ts（Node ランタイム）— middleware.ts（Edge）ではありません
• 明示的な 'use cache' — 暗黙的な fetch キャッシュではありません
• revalidateTag(tag, cacheLife) — 引数が1つだけの revalidateTag(tag) ではありません
• Server Action + useActionState — クライアントの fetch + useState ではありません
• app/sitemap.ts — 手動管理の public/sitemap.xml ではありません

よくある単一ファイルのミス — これらのアンチパターンを避けてください：

• 独立したデータを順番に await する（Promise.all またはプリロードを使用します）
• 初期ページデータの取得に Client Component 内で useEffect + fetch を使う
• インタラクティブなボタンが1つあるだけで、レイアウトレベルに 'use client' を指定する
• ミューテーションを行う Server Action の後に revalidatePath／revalidateTag を呼び出さない
• コンテンツの寸法と一致しないスケルトン（CLS が発生します）

コードベースレベルのパターン — カテゴリ9の点検では、以下を確認してください：

• 2つ以上の Server Component が同じ上流サービスにアクセスし、キャッシュポリシーにばらつきがある — 共通のキャッシュ付き fetcher に抽出します
• バリアントや動的セグメントで1つにまとめるべき、ほぼ重複したルート／レイアウトが2つ以上ある — 統合します
• 90日以上、流入トラフィックがないルート／ルートハンドラー／Server Action — （分析データを確認した後に）削除します
• インタラクティブなリーフが1つあるためにルートツリーの上位へ 'use client' が伝播している — レイアウト／親を Server Component に戻し、クライアントアイランドを残します
• ルートパラメーター／検索パラメーター／props の名前が異なるだけで同じ概念を表している — 正規の名前に統一します（SEO リダイレクトに注意してください）

目次

1. ビルドとバンドルの最適化 — 重大
   • 1.1 バレルファイル index.ts ではなく、ソースモジュールからインポートする — 重大（開発時の起動が2～10倍高速）
   • 1.2 optimizePackageImports でパッケージ直下エクスポートのライブラリを宣言する — 重大（インポートが200～800ms高速化、バンドルが50～80％縮小）
   • 1.3 ネイティブバインディングを含むNodeパッケージを serverExternalPackages としてマークする — 高
   • 1.4 Turbopackの永続キャッシュを無効にしない — 重大（コールドスタートが5～10倍高速）
   • 1.5 重いコンポーネントを個別に読み込むチャンクに分割する — 重大（初期バンドルが30～70％縮小）
2. キャッシュ戦略 — 重大
   • 2.1 すべてのサーバー fetch でキャッシュの意図を宣言する — 高
   • 2.2 セグメント設定のエクスポートでルートレベルのキャッシュを宣言する — 中～高
   • 2.3 'use cache' でキャッシュ可能なServer Component／関数を明示的にマークする — 重大
   • 2.4 revalidateTag(tag, cacheLife) をプロファイルとともに呼び出す — 重大
   • 2.5 データを表示するルート／タグを、変更を行うすべてのServer Actionで無効化する — 高
   • 2.6 リクエストごとのフェッチ関数をReactの cache() でラップして重複を排除する — 高
3. Server Componentとデータ取得 — 高
   • 3.1 独立したサーバー側フェッチは並行して実行する — 順次の await はウォーターフォールを引き起こす — 高
   • 3.2 非同期処理のペースが独立している各リーフを、それぞれ独自の <Suspense> でラップする — 高
   • 3.3 各Server Componentで、レンダリングするデータを取得する — 高
   • 3.4 preload 呼び出しでクリティカルなデータ取得を早期に開始する — 中～高
   • 3.5 初期ページデータはServer Component経由でHTMLに含める — useEffect+fetch は使わない — 中～高
   • 3.6 error.tsx または ErrorBoundary で非同期エラーを捕捉する — 中
4. ルーティングとナビゲーション — 高
   • 4.1 複数リージョンのレイアウトにはパラレルルートのスロットを使う — 高
   • 4.2 モーダル／ライトボックス形式の詳細ビューにはインターセプトルートを使う — 高
   • 4.3 <Link prefetch> をトラフィックの可能性に応じて調整する — 中～高
   • 4.4 ネットワーク境界のロジックは middleware.ts ではなく proxy.ts に置く — 中～高
   • 4.5 存在しない動的リソースでは notFound() を呼び出し、正しいHTTP 404を返す — 中
5. Server Actionと変更処理 — 中～高
   • 5.1 フォームからの変更処理にはServer Actionを使う — APIルートとクライアント側 fetch の組み合わせは使わない — 中～高
   • 5.2 送信ボタンでは useFormStatus から親フォームの処理中状態を取得する — 中～高
   • 5.3 Server Actionは型付けされたエラー／状態の結果を返す — エラーを黙ってスローしない — 中～高
   • 5.4 UIの結果を予測できる変更処理には楽観的更新を適用する — 中
   • 5.5 データを表示するルート／タグを、すべてのServer Actionで無効化する — 中
6. ストリーミングと読み込み状態 — 中
   • 6.1 処理のペースが独立しているサブツリーをそれぞれSuspenseで囲む — 中
   • 6.2 すべてのルートで、page.tsx の隣に loading.tsx を置く — 中
   • 6.3 すべてのルートで、隣に error.tsx を置く — 中
   • 6.4 スケルトンの寸法を、置き換えるコンテンツの寸法に合わせる — 中
   • 6.5 コンテンツに自然な表示順がある場合はSuspenseをネストする — 低～中
7. メタデータとSEO — 中
   • 7.1 動的ルートで generateMetadata をエクスポートし、リソースごとのSEO情報を設定する — 中
   • 7.2 実際のデータからサイトマップを生成する — XMLを手作業で管理しない — 中
   • 7.3 app/robots.ts とページごとのメタデータでクロールルールを明示する — 中
   • 7.4 opengraph-image.tsx でページごとのOG画像を生成する — 低～中
8. クライアントコンポーネント — 低～中
   • 8.1 'use client' をインタラクティブなリーフまで移動する — 低～中
   • 8.2 Server Componentのコンテンツを children 経由でClient Componentの内側に渡す — 低～中
   • 8.3 SSRとクライアントの初回レンダリングで同一のHTMLを生成する — 低～中
   • 8.4 サードパーティスクリプトを適切な strategy を指定して next/script でラップする — 低～中
9. コードベースの整理 — 横断的（複数ファイルに関する指摘。リポジトリ全体の監査に必要）
   • 9.1 重複するサーバー側フェッチ関数／アクションを共有モジュールに抽出する — 高
   • 9.2 よく似たルート／レイアウト／コンポーネントを統合する — 高
   • 9.3 到達不能なルート、未使用のServer Action、孤立したユーティリティを削除する — 中～高
   • 9.4 ルートツリー全体で 'use client' の配置を監査する — 高
   • 9.5 ルート／コンポーネント間で、同じ概念には一貫した正式名称を使う — 中～高

参考資料

1. Next.js ドキュメント
2. Next.js 16 リリースノート
3. React ドキュメント
4. Vercel エンジニアリングブログ

関連スキル

• React 19 の基礎（並行レンダリング、フック、コンポーネント）については、react スキルを参照してください
• クライアントサイドのフォーム処理については、react-hook-form スキルを参照してください
• TanStack Query を使ったクライアントデータのキャッシュについては、tanstack-query スキルを参照してください

コンパイル済みドキュメント全文

すべてのルールを展開したガイド全文については、AGENTS.md を参照してください