vue-best-practices

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

このスキルを手順として使用してください。ユーザーが明示的に別の順序を求めていない限り、ワークフローの順に進めてください。

基本原則

• 状態を予測可能に保つ： 信頼できる唯一の情報源を設け、それ以外はすべてそこから導出します。
• データフローを明示する： ほとんどの場合、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 コーディング前にコンポーネントの境界を計画する（必須）

重要な機能を実装する場合は、実装前に簡潔なコンポーネントマップを作成します。

• 各コンポーネントの単一の責務を一文で定義します。
• エントリー／ルートコンポーネントとルートレベルのビューコンポーネントは、デフォルトで構成を担う場所として維持します。
• 意図的に小さな単一ファイルのデモを作成する場合を除き、機能 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 の構成とテンプレートのルールに従っている。
• コンポーネントの役割が明確で、適切に分割されている。必要に応じて分割する。
• 明示的な小規模デモの例外を除き、エントリー／ルートコンポーネントとルートビューコンポーネントはコンポジションのための領域として維持されている。
• コンポーネントを分割する判断が明確で、正当化できる（責務の境界が明確である）。
• データフローの契約が明確で、型付けされている。
• 再利用性や複雑さに応じてコンポーザブルを使用している。
• 該当する場合、状態や副作用をコンポーザブルに移している
• オプション機能は要件で求められる場合にのみ使用している。
• パフォーマンス改善は機能の完成後にのみ適用している。