Geruyang/agent-skills-library

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

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

ファイル規約

file-conventions.md を参照:

• プロジェクト構造と特殊ファイル
• ルートセグメント（動的、キャッチオール、グループ）
• パラレルルートとインターセプトルート
• v16 でのミドルウェアの名称変更（middleware → proxy）

RSC 境界

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

rsc-boundaries.md を参照:

• 非同期クライアントコンポーネントの検出（無効）
• シリアライズ不可なプロパティの検出
• 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 vs Server Actions vs Route Handlers
• データウォーターフォールの回避（Promise.all、Suspense、preload）
• クライアントコンポーネントのデータフェッチ

ルートハンドラ

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 vs ネイティブ 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 を用いた特定ルートの再構築