nextjs

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を参照してください。内容は次のとおりです。

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

関数

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、preload）
• クライアントコンポーネントでのデータ取得

Route Handlers

route-handlers.mdを参照してください。内容は次のとおりです。

• route.ts の基本
• GET ハンドラーと page.tsx の競合
• 環境の動作（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 エラー

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 を使って特定のルートを再ビルドする方法