next-best-practices

（中国語）Next.js のベストプラクティス

Next.js コードを記述またはレビューする際は、以下のルールを適用してください。

ファイル規約

file-conventions.md を参照してください。

• プロジェクト構造と特殊ファイル
• ルートセグメント（動的、キャッチオール、グループ）
• 並列ルートとインターセプトルート
• v16 でのミドルウェアの名称変更（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.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 を使って特定のルートを再ビルドする