accelint-nextjs-best-practices

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

Next.js アプリケーション向けの包括的なパフォーマンス最適化とベストプラクティスです。Next.js のコードを扱う AI エージェントと LLM 向けに設計されています。

このスキルを使用するタイミング

次のようなタスクでは、このスキルを使用してください。

Next.js コードの作成

• サーバーコンポーネントまたはクライアントコンポーネントの作成
• "use server" を使用したサーバーアクションの実装
• API ルートハンドラーの作成
• RSC（React Server Components）でのデータ取得の設定
• Suspense 境界の実装
• Next.js 固有の API（headers()、cookies()、after()）の使用

Next.js コードのリファクタリング

• サーバー側のデータ取得の最適化
• RSC のシリアライズに伴うオーバーヘッドの削減
• 逐次処理から並列処理への変換
• パフォーマンス向上を目的としたコンポーネント構成の再設計
• サーバーコンポーネントとクライアントコンポーネント間の移行

パフォーマンスの最適化

• サーバー側のウォーターフォールの解消
• API ルートとサーバーアクションの応答時間の短縮
• RSC 境界で転送されるデータ量の最小化
• React.cache() によるリクエストの重複排除の実装
• ブロッキングを避ける処理での after() の使用

Next.js 固有の問題

• サーバーアクションでの認証と認可
• RSC のシリアライズで発生する重複の問題
• インポートの最適化（バレルファイルの問題）
• サーバーコンポーネントとクライアントコンポーネントの選択
• 並列データ取得のパターン

コードレビュー

• Next.js コードのパフォーマンスに関するアンチパターンのレビュー
• サーバーアクションのセキュリティ問題の特定
• サーバーコンポーネントとクライアントコンポーネントの境界の適切さの確認
• 適切な認証パターンの確認
• Suspense 境界の配置の検証

このスキルを使用しないタイミング

次の場合は、このスキルを有効にしないでください。

• React 固有の最適化（accelint-react-best-practices スキルを使用してください）
• ビルド設定（webpack、turbopack）。ただし、Next.js 固有の場合を除きます
• 一般的な TypeScript／JavaScript に関する質問（accelint-ts-best-practices スキルを使用してください）
• デプロイ／ホスティングの設定
• テストの設定（accelint-ts-testing スキルを使用してください）

トリガーとなるフレーズの例

ユーザーが次のようなことを言った場合、このスキルが有効になります。

パフォーマンスの問題：

• 「この Next.js API ルートは遅いです」
• 「サーバーコンポーネントがページ全体をブロックしています」
• 「このサーバーアクションを最適化してください」
• 「ページのデータ読み込みに時間がかかりすぎます」
• 「データ取得でウォーターフォールが発生しています」

セキュリティの問題：

• 「このサーバーアクションに認証を追加してください」
• 「このサーバーアクションには認可が必要です」
• 「この API ルートを安全にしてください」
• 「このサーバーアクションで入力を検証してください」

デバッグの問題：

• 「RSC の props が大きすぎるのはなぜですか？」
• 「このデータが HTML 内で重複しています」
• 「開発環境でインポートが遅いです」
• 「これはサーバーコンポーネントとクライアントコンポーネントのどちらにすべきですか？」

コードレビュー：

• 「パフォーマンスの問題がないか、この Next.js コードをレビューしてください」
• 「このサーバーアクションは安全ですか？」
• 「このデータ取得を最適化できますか？」
• 「このコンポーネントをサーバー側とクライアント側のどちらにすべきか確認してください」

リファクタリング：

• 「これらのデータ取得を並列化してください」
• 「シリアライズされるデータのサイズを削減してください」
• 「これを Suspense を使う形に変換してください」
• 「このバレルインポートを最適化してください」

使用方法

このスキルは、コンテキストの使用量を最小限に抑えるため、段階的な開示の構成を採用しています。

1. 概要から始める（AGENTS.md）

すべてのルールを簡潔にまとめた概要を確認するには、AGENTS.md を読んでください。

2. 必要に応じて特定のルールを読み込む

関連する最適化を特定したら、詳細な実装ガイダンスを確認するために、対応するリファレンスファイルを読み込みます。

一般的なパターン：

• prevent-waterfall-chains.md (1.1)
• parallelize-independent-operations.md (1.2)
• strategic-suspense-boundaries.md (1.3)

サーバーサイドのパフォーマンス：

• server-actions-security.md (2.1)
• avoid-duplicate-serialization.md (2.2)
• minimize-serialization.md (2.3)
• parallel-data-fetching.md (2.4)
• react-cache-deduplication.md (2.5)
• use-after-non-blocking.md (2.6)

その他：

• avoid-barrel-imports.md (3.1)
• server-vs-client-component.md (3.2)

クイックリファレンス：

• quick-checklist.md
• compound-patterns.md

自動化スクリプト：

• scripts/ - アンチパターンを検出するヘルパースクリプト

3. パターンを適用する

各リファレンスファイルには、次の内容が含まれています。

• ❌ アンチパターンを示す誤った例
• ✅ 最適な実装を示す正しい例
• そのパターンが重要な理由の説明
• パフォーマンスへの影響を示す指標
• 関連するパターンとリファレンス

4. レポートテンプレートを使用する

このスキルが Next.js のコードレビューで呼び出された場合は、標準化されたレポート形式を使用します。

テンプレート： assets/output-report-template.md

レポート形式には、次の内容が含まれています。

• 影響評価を含むエグゼクティブサマリー
• 優先順位付けのための重大度レベル（重大、高、中、低）
• 影響分析（パフォーマンス、セキュリティ、データ転送、保守性）
• 分類（Server Actions、RSC のシリアライズ、データ取得、コンポーネントのアーキテクチャ）
• references/ 内の詳細なガイダンスへのリンクを含むパターンリファレンス
• すべての問題を追跡するためのサマリーテーブル

レポートテンプレートを使用する場合：

• スキルが /accelint-nextjs-best-practices <path> 経由で直接呼び出された場合
• ユーザーがファイル全体にわたって「Next.js のコードをレビュー」または「Next.js アプリを監査」するよう依頼し、スキルが暗黙的に呼び出された場合

レポートテンプレートを使用しない場合：

• ユーザーが「この Server Action を修正して」と依頼した場合（直接実装）
• ユーザーが「このコードの何が問題ですか？」と尋ねた場合（質問に回答）
• ユーザーが具体的な修正を依頼した場合（正式なレポートを作成せず、直接修正を適用）

例

例 1: Server Action のセキュリティを最適化する

タスク：「この Server Action に認証を追加する」

アプローチ：

1. AGENTS.md の概要を読む
2. 問題を特定する：Server Action に認証が必要
3. server-actions-security.md を読み込む
4. 検証を伴う認証パターンを適用する

例 2: ウォーターフォールを解消する

タスク：「このページは複数の fetch を行うため、読み込みが遅い」

アプローチ：

1. AGENTS.md の概要を読む
2. 問題を特定する：データを順次取得している
3. prevent-waterfall-chains.md と parallelize-independent-operations.md を読み込む
4. 処理をすぐに開始し、Promise.allSettled() を使用する

例 3: シリアライズを減らす

タスク：「ユーザーデータのために HTML レスポンスが巨大です」

アプローチ：

1. AGENTS.md の概要を読む
2. 問題を特定する：RSC の境界で過剰にシリアライズしている
3. minimize-serialization.md を読み込む
4. 必要なフィールドのみを渡し、クライアント側で変換する

Additional Resources

Official Next.js documentation:

• App Router Documentation
• Server Components
• Server Actions
• Authentication Guide
• Performance Optimization