next-best-practices

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

Next.js コードの作成やレビューでは、これらのルールを適用してください。

ファイル規約

file-conventions.md で、以下について説明しています。

• プロジェクト構造と特別なファイル
• ルートセグメント（動的、キャッチオール、グループ）
• 並列ルートとインターセプトルート
• v16 での Middleware の名称変更（middleware → proxy）

RSC の境界

無効な React Server Component のパターンを検出します。

rsc-boundaries.md で、以下について説明しています。

• 非同期クライアントコンポーネントの検出（無効）
• シリアライズできない props の検出
• Server Action の例外

非同期パターン

Next.js 15 以降の非同期 API の変更点です。

async-patterns.md で、以下について説明しています。

• 非同期の params と searchParams
• 非同期の cookies() と headers()
• 移行用 codemod

ランタイムの選択

runtime-selection.md で、以下について説明しています。

• Node.js ランタイムをデフォルトにする
• Edge ランタイムが適している場合

ディレクティブ

directives.md で、以下について説明しています。

• 'use client'、'use server'（React）
• 'use cache'（Next.js）

関数

functions.md で、以下について説明しています。

• ナビゲーションフック：useRouter、usePathname、useSearchParams、useParams
• サーバー関数：cookies、headers、draftMode、after
• 生成関数：generateStaticParams、generateMetadata

エラー処理

error-handling.md で、以下について説明しています。

• error.tsx、global-error.tsx、not-found.tsx
• redirect、permanentRedirect、notFound
• forbidden、unauthorized（認証エラー）
• catch ブロックでの unstable_rethrow

データパターン

data-patterns.md で、以下について説明しています。

• Server Components、Server Actions、Route Handlers の使い分け
• データのウォーターフォールを回避する方法（Promise.all、Suspense、プリロード）
• クライアントコンポーネントでのデータ取得

Route Handlers

route-handlers.md で、以下について説明しています。

• route.ts の基本
• page.tsx と競合する GET ハンドラー
• 環境の動作（React DOM なし）
• Server Actions との使い分け

メタデータと OG 画像

metadata.md で、以下について説明しています。

• 静的および動的なメタデータ
• generateMetadata 関数
• next/og による OG 画像の生成
• ファイルベースのメタデータ規約

画像の最適化

image.md で、以下について説明しています。

• <img> よりも常に next/image を使用する
• リモート画像の設定
• レスポンシブな sizes 属性
• ぼかしプレースホルダー
• LCP の優先読み込み

フォントの最適化

font.md で、以下について説明しています。

• next/font のセットアップ
• Google Fonts、ローカルフォント
• Tailwind CSS との統合
• サブセットのプリロード

バンドル

bundling.md で、以下について説明しています。

• サーバー非対応のパッケージ
• CSS のインポート（link タグではなく）
• ポリフィル（すでに含まれています）
• ESM/CommonJS の問題
• バンドルの分析

スクリプト

scripts.md で、以下について説明しています。

• next/script とネイティブの script タグの使い分け
• インラインスクリプトに必要な id
• 読み込み戦略
• @next/third-parties による Google Analytics

ハイドレーションエラー

hydration-error.md で、以下について説明しています。

• よくある原因（ブラウザー API、日付、無効な HTML）
• エラーオーバーレイを使ったデバッグ
• 原因ごとの修正方法

Suspense の境界

suspense-boundaries.md で、以下について説明しています。

• useSearchParams と usePathname による CSR への切り替え
• Suspense の境界が必要なフック

並列ルートとインターセプトルート

parallel-routes.md で、以下について説明しています。

• @slot と (.) インターセプターを使ったモーダルのパターン
• フォールバック用の default.tsx
• router.back() を使った正しいモーダルの終了方法

セルフホスティング

self-hosting.md で、以下について説明しています。

• Docker 用の output: 'standalone'
• 複数インスタンスの ISR に対応するキャッシュハンドラー
• そのまま動作する機能と、追加の設定が必要な機能

デバッグのヒント

debug-tricks.md で、以下について説明しています。

• AI 支援デバッグ用の MCP エンドポイント
• --debug-build-paths を使った特定ルートの再ビルド