vue-best-practices

Vue のベストプラクティスワークフロー

このスキルは指示セットとして使用してください。ユーザーが明示的に別の順序を求めない限り、ワークフローに記載された順序で進めてください。

基本原則

• 予測可能な状態を保つ： 信頼できる情報源を1つにし、それ以外はすべてそこから導出します。
• データフローを明確にする： ほとんどの場合、Props を下方向に渡し、Events を上方向に送ります。
• 小さく、役割を絞ったコンポーネントを優先する： テスト、再利用、保守が容易になります。
• 不要な再レンダリングを避ける： computed プロパティとウォッチャーを適切に使用します。
• 読みやすさを重視する： 明確で、コード自体が説明となるコードを書きます。

1) コーディング前にアーキテクチャを確認する（必須）

• デフォルトのスタック：Vue 3 + Composition API + <script setup lang="ts">。
• プロジェクトで Options API が明示的に使用されている場合は、利用可能であれば vue-options-api-best-practices スキルを読み込んでください。
• プロジェクトで JSX が明示的に使用されている場合は、利用可能であれば vue-jsx-best-practices スキルを読み込んでください。

1.1 必ず読む基本リファレンス（必須）

• Vue のタスクを実装する前に、次の基本リファレンスを必ず読み、内容を適用してください。
  • references/reactivity.md
  • references/sfc.md
  • references/component-data-flow.md
  • references/composables.md
• 特定の問題が発生したときだけでなく、タスク全体を通してこれらのリファレンスを作業コンテキストに保持してください。

1.2 コーディング前にコンポーネントの境界を計画する（必須）

簡単な単一ファイルのデモを意図している場合を除き、複雑な機能では実装前に簡潔なコンポーネントマップを作成してください。

• 各コンポーネントの単一の責務を1文で定義します。
• デフォルトでは、エントリー／ルートコンポーネントとルートレベルのビューコンポーネントを構成のための場として維持します。
• タスクが意図的に小規模な単一ファイルのデモである場合を除き、機能の UI とロジックをエントリー／ルート／ビューコンポーネントの外に移します。
• マップ内で、各子コンポーネントの props／emits コントラクトを定義します。
• コンポーネントを複数追加する場合は、機能別フォルダー構成（components/<feature>/...、composables/use<Feature>.ts）を優先します。

2) Vue の基本原則を適用する（必須）

これらは必須の基本原則です。セクション 1.1 で読み込んだ基本リファレンスを使い、Vue のすべてのタスクで適用してください。

リアクティビティ

• 1.1 の必読リファレンス：リアクティビティ
• ソースとなる状態は最小限（ref／reactive）にし、可能な限りすべてを computed で導出します。
• 必要に応じて、副作用にはウォッチャーを使用します。
• テンプレート内で高コストなロジックを再計算しないでください。

SFC の構造とテンプレートの安全性

• 1.1 の必読リファレンス：SFC
• SFC のセクションは、<script> → <template> → <style> の順にします。
• SFC の責務を絞り、大きなコンポーネントは分割します。
• テンプレートは宣言的に保ち、分岐や導出はスクリプトに移します。
• Vue のテンプレートの安全性に関するルール（v-html、リスト描画、条件付き描画の選択）を適用します。

コンポーネントに明確な責務を持たせる

コンポーネントに複数の明確な責務（例：データのオーケストレーションと UI、または複数の独立した UI セクション）がある場合は、分割してください。

• 1 つの「巨大なコンポーネント」よりも、小さなコンポーネントとコンポーザブルを優先します。
• UI セクションは子コンポーネントに移します（props を受け取り、イベントを送信します）。
• 状態や副作用はコンポーザブル（useXxx()）に移します。

客観的な分割条件を適用してください。次の条件のいずれかに当てはまる場合は、コンポーネントを分割します。

• オーケストレーション／状態管理と、複数のセクションにわたる大規模なプレゼンテーション用マークアップの両方を担っている。
• 明確に異なる UI セクションが 3 つ以上ある（例：フォーム、フィルター、リスト、フッター／ステータス）。
• テンプレートブロックが繰り返されている、または再利用可能な要素にできる（項目の行、カード、リスト項目）。

エントリ／ルートおよびルートビューのルール：

• エントリ／ルートおよびルートビューのコンポーネントは薄く保ちます。担当するのは、アプリシェル／レイアウト、プロバイダーの接続、機能の構成です。
• 独立した部分を含む機能の実装全体を、エントリ／ルート／ビューのコンポーネントに配置しないでください。
• CRUD／リスト機能（todo、table、catalog、inbox）は、少なくとも次のように分割します。
  • 機能コンテナーコンポーネント
  • 入力／フォームコンポーネント
  • リスト（および／または項目）コンポーネント
  • フッター／アクションまたはフィルター／ステータスコンポーネント
• 非常に小規模な使い捨てデモに限り、単一ファイルでの実装を認めます。単一ファイルでの実装を選ぶ場合は、分割が不要な理由を明記してください。

コンポーネントのデータフロー

• 1.1 で必ず読むリファレンス：component-data-flow
• 基本モデルとして、props を下方向に渡し、イベントを上方向に送信します。
• 真の双方向コンポーネント契約に限り、v-model を使用します。
• 深いツリー内での依存関係や共有コンテキストに限り、provide/inject を使用します。
• 必要に応じて defineProps、defineEmits、InjectionKey を使い、契約を明示的かつ型付きに保ちます。

コンポーザブル

• 1.1 で必ず読むリファレンス：composables
• ロジックが再利用される場合、状態を持つ場合、または副作用が多い場合は、コンポーザブルに抽出します。
• コンポーザブルの API は、小さく、型付きで、予測可能なものにします。
• 機能ロジックとプレゼンテーション用コンポーネントを分離します。

3) 要件がある場合にのみ、オプション機能を検討する

3.1 標準のオプション機能

これらはデフォルトで追加しないでください。要件がある場合に限り、該当するリファレンスを読み込みます。

• スロット：親が子のコンテンツ／レイアウトを制御する必要がある場合 → component-slots
• フォールスルー属性：ラッパー／ベースコンポーネントが属性／イベントを安全に転送する必要がある場合 → component-fallthrough-attrs
• 状態を持つビューのキャッシュには、組み込みコンポーネント <KeepAlive> を使用 → component-keep-alive
• オーバーレイ／ポータルには、組み込みコンポーネント <Teleport> を使用 → component-teleport
• 非同期サブツリーのフォールバック境界には、組み込みコンポーネント <Suspense> を使用 → component-suspense
• アニメーション関連機能：必要なモーション動作に合う最も単純な方法を選びます。
  • 入場／退場エフェクトには、組み込みコンポーネント <Transition> を使用 → transition
  • アニメーション付きリスト変更には、組み込みコンポーネント <TransitionGroup> を使用 → transition-group
  • 入場／退場以外のエフェクトには、クラスベースのアニメーションを使用 → animation-class-based-technique
  • ユーザー入力に応じたアニメーションには、状態駆動型アニメーションを使用 → animation-state-driven-technique

3.2 あまり一般的ではないオプション機能

明確な製品上または技術上の必要性がある場合にのみ使用してください。

• ディレクティブ：動作が DOM 固有で、コンポーザブルやコンポーネントに適さない場合 -> directives
• 非同期コンポーネント：重い UI や使用頻度の低い UI を遅延読み込みする場合 -> component-async
• テンプレートでは要件を表現できない場合に限り、レンダー関数を使用します -> render-functions
• 動作をアプリ全体にインストールする必要がある場合は、プラグインを使用します -> plugins
• 状態管理パターン：アプリ全体で共有する状態が機能の境界をまたぐ場合 -> state-management

4) 動作が正しくなってからパフォーマンスを最適化する

パフォーマンス改善は、機能実装後に行います。主要な動作を実装して検証する前に最適化しないでください。

• 大規模なリストのレンダリングがボトルネックになる場合 -> perf-virtualize-large-lists
• 静的なサブツリーが不必要に再レンダリングされる場合 -> perf-v-once-v-memo-directives
• リストのホットパスで過度に抽象化されている場合 -> perf-avoid-component-abstraction-in-lists
• コストの高い更新が頻繁に引き起こされる場合 -> updated-hook-performance

5) 完了前の最終セルフチェック

• 主要な動作が機能し、要件に合致している。
• 必読の参照資料をすべて読み、内容を反映している。
• リアクティビティモデルが最小限で、予測可能である。
• SFC の構成とテンプレートのルールに従っている。
• コンポーネントの役割が明確で、適切に分割されている。必要に応じて分割する。
• 明示的な小規模デモの例外を除き、エントリー／ルートコンポーネントとルートビューコンポーネントはコンポジションのための領域として維持されている。
• コンポーネントを分割する判断が明確で、正当化できる（責務の境界が明確である）。
• データフローの契約が明確で、型付けされている。
• 再利用性や複雑さに応じてコンポーザブルを使用している。
• 該当する場合、状態や副作用をコンポーザブルに移している
• オプション機能は要件で求められる場合にのみ使用している。
• パフォーマンス改善は機能の完成後にのみ適用している。