nuxt-best-practices

Nuxt のベストプラクティス

Nuxt 4 アプリケーション向けの包括的なパフォーマンス最適化ガイドです（現在：Nuxt 4.5、EOL が近づく 3.x アプリケーション向けの注記を含みます）。影響度に基づいて優先順位付けされた 9 カテゴリー、23 のルールを収録し、自動リファクタリングとコード生成を支援します。

適用するタイミング

次の場合に、これらのガイドラインを参照してください。

• 新しい Nuxt ページ、コンポーネント、コンポーザブルを作成するとき
• データフェッチを実装するとき（useFetch、useAsyncData、4.5 の enabled オプション）
• サーバールートと API エンドポイントを作成するとき
• 型、コンポーザブル、自動インポートを整理するとき
• Nuxt モジュールとプラグインを扱うとき
• レンダリングモード（SSR、SSG、SPA、4.5 の実験的な SSR ストリーミング）を設定するとき
• レイアウト、名前付きビュー、NuxtLink のプリフェッチ（Nuxt 4.5 の規約）を使用するとき

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス
1	データフェッチ	CRITICAL	data-
2	自動インポートと整理	CRITICAL	imports-
3	サーバーと API ルート	HIGH	server-
4	レンダリングモード	HIGH	rendering-
5	状態管理	MEDIUM-HIGH	state-
6	ページ、レイアウト、ナビゲーション	MEDIUM	pages-
7	型安全性	MEDIUM	types-
8	モジュールとプラグイン	LOW-MEDIUM	modules-
9	パフォーマンスとデプロイ	LOW	perf-

クイックリファレンス

1. データフェッチ（CRITICAL）

• data-use-fetch - useFetch/useAsyncData を使用し、コンポーネント内で生の fetch を使用しない
• data-key-unique - データフェッチには必ず一意のキーを指定する
• data-lazy-loading - 重要でないデータには lazy オプションを使用する
• data-transform - テンプレート内ではなく、フェッチ時にデータを変換する
• data-error-handling - エラー状態と保留状態を必ず処理する
• data-refresh-patterns - refresh() と clear() を適切に使用する
• data-conditional-enabled - 条件付きフェッチには enabled オプションを使用する（4.5 以降）

2. 自動インポートと整理（CRITICAL）

• imports-no-barrel-autoimport - 自動インポートされるディレクトリにバレルエクスポートを作成しない
• imports-component-naming - コンポーネント名でフォルダーのプレフィックスを重複させない
• imports-type-locations - 型は専用ディレクトリ（app/types、shared/types、server/types）に配置する
• imports-composable-exports - コンポーザブルがエクスポートするのは関数のみとし、型はエクスポートしない
• imports-direct-composable-imports - コンポーザブル間では直接インポートを使用する

3. サーバーと API ルート（HIGH）

• server-validated-input - Zod とともに getValidatedQuery/readValidatedBody を使用する
• server-route-meta - OpenAPI ドキュメント用に defineRouteMeta を必ず追加する
• server-runtime-config - useRuntimeConfig を使用し、process.env は使用しない
• server-error-handling - 一貫したエラーレスポンスには createError を使用する
• server-middleware-order - ミドルウェアの実行順序を理解する

4. レンダリングモード（HIGH）

• rendering-route-rules - routeRules でルートごとにレンダリングを設定する
• rendering-hybrid - パフォーマンスを最適化するためにハイブリッドレンダリングを使用する
• rendering-prerender - ビルド時に静的ページをプリレンダリングする
• rendering-client-only - ブラウザー固有のコンポーネントには ClientOnly を使用する
• rendering-ssr-streaming - SSR ストリーミングを有効にする前に、その仕組みを理解する（4.5 以降、実験的）

5. 状態管理（MEDIUM-HIGH）

• state-use-state - SSR に安全な共有状態には useState を使用する
• state-pinia-setup - Nuxt で Pinia を正しくセットアップする
• state-hydration - ハイドレーションの不一致を適切に処理する
• state-computed-over-watch - 派生状態には watch より computed を優先する

6. ページ、レイアウト、ナビゲーション（MEDIUM）

• pages-use-layout - 解決済みのレイアウトを読み取るには useLayout を使用する（4.5 以降）
• pages-named-views - 名前付きビューには [email protected] 規約を使用する（4.5 以降）
• pages-nuxtlink-custom-prefetch - NuxtLink のカスタムスロットでは、プリフェッチを手動で設定する（4.5 以降）

7. 型安全性（中）

• types-no-inline - コンポーネントやコンポーザブル内で型をインライン定義しないでください
• types-import-paths - 正しいインポートパス（#shared、~/、~~/）を使用してください
• types-no-any - any 型は使用しないでください
• types-zod-schemas - 型推論を利用した実行時検証には Zod を使用してください
• types-strict-emits - emit の型を完全に指定してください。camelCase で宣言し、kebab-case でリッスンします

8. モジュールとプラグイン（低〜中）

• modules-order - nuxt.config ではモジュールの順序が重要です
• modules-runtime-vs-build - 実行時モジュールとビルド時モジュールの違いを理解してください
• plugins-client-server - .client.ts と .server.ts のサフィックスを正しく使用してください
• plugins-provide-inject - 横断的な関心事には provide/inject を使用してください

9. パフォーマンスとデプロイ（低）

• perf-bundle-analysis - バンドルサイズを分析して最適化してください
• perf-image-optimization - 画像を最適化するには nuxt/image を使用してください
• perf-font-loading - フォントの読み込み戦略を設定してください
• perf-caching-headers - 適切なキャッシュヘッダーを設定してください

使用方法

詳しい説明とコード例については、個別のルールファイルを参照してください。

rules/data-use-fetch.md
rules/imports-no-barrel-autoimport.md
rules/_sections.md

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

• 重要である理由の簡単な説明
• 誤ったコード例とその説明
• 正しいコード例とその説明
• 補足情報と Nuxt 固有の注意事項

コンパイル済みドキュメント全文

すべてのルールを詳しく説明した完全なガイドについては、AGENTS.md を参照してください。