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 コーディング前にコンポーネントの境界を計画する（必須）

複雑な機能や構造的なリファクタリングでは、責務、状態の所有者、境界をまたぐ契約を図にまとめてください。局所的な修正では、既存の境界が変更の妨げにならない限り、それを維持してください。

• 影響を受ける機能における、主要な UI の責務、状態を持つワークフロー、DOM のライフサイクルを特定してください。それらの所有者、利用者、連携に必要な契約を図にまとめてください。
• 挙動が一緒に変化すること、または共通の不変条件を保つことを基準に凝集度を判断してください。同じページにあること、同じデータを参照すること、利用者が1つしかいないことだけでは、1つの実装にまとめる根拠になりません。
• ルートコンポーネントには、機能の組み立てとページの動作の調整を任せてください。機能コンポーネントや composable の内部でも同様に責務を見直してください。機能全体を子コンポーネントや useFeature() 関数に移すだけでは、適切な分割とはいえません。
• プロジェクトの構成に従い、影響を受ける挙動の規模に合わせて設計してください。局所的な修正に、プロジェクト全体のコンポーネント図や新たなアーキテクチャレイヤーは必要ありません。

2) Vue の基礎を適用する（必須）

以下は必須の基礎知識です。セクション 1.1 で読み込んだコアリファレンスを使用し、すべての Vue タスクで適用してください。

リアクティビティ

• 1.1 の必読リファレンス：reactivity
• ソースとなる状態（ref／reactive）は最小限にし、可能な限りすべてを computed で導出してください。
• 必要に応じて、副作用にはウォッチャーを使用してください。
• テンプレート内で負荷の高い処理を繰り返さないでください。

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

• 1.1 の必読リファレンス：sfc
• SFC の各セクションは、<script> → <template> → <style> の順に並べてください。
• SFC の責務に一貫性を持たせ、分割する際は以下の境界基準を適用してください。
• テンプレートは宣言的に保ち、分岐や導出処理は script に移してください。
• Vue テンプレートの安全性に関するルール（v-html、リストのレンダリング、条件付きレンダリングの選択）を適用してください。

有用な境界を選ぶ

• コードを利用する側や保守する側が理解すべき内容を減らせる場合は、相互に切り離せるまとまりのある UI の責務や、状態を伴うワークフローを抽出します。単一箇所でのみ使用するコンポーネントやコンポーザブルも有効であり、再利用できることは前提ではありません。UI の責務に必要な状態管理とイベント処理は、その UI と一緒に置きます。
• 構造をリファクタリングする際は、上記で特定した責務に役立つ境界を設けます。抽出したものだけでなく、残したものもまとめて見直します。公開 API が小さくても、その内部実装をさらに分解する必要がある場合があります。
• ファイルの長さ、UI セクションの数、API の規模は、レビュー時の判断材料として扱い、抽出の基準にはしません。境界を追加しても意味のある複雑さを隠せない場合は、まとまりのある小規模な本番機能を 1 つの SFC にまとめておきます。
• 分割によって大規模な中継処理や相互のコールバックが増える場合は、まずローカル状態と DOM の動作を、それらを所有する UI に移します。次に、本当に共有される依存関係とそのライフタイムを特定します。必要に応じて、明示的なコントラクトやスコープ付きコンテキストを使います。単に配線を減らすためではなく、その境界にカプセル化する価値のある責務がない場合にのみ統合します。
• 入力をまとめるのは、それらがまとまりのある概念を構成する場合に限ります。コントローラー全体を渡したり、無関係なハンドラーをまとめたり、あらゆる処理を受け持つイベントを追加したりしても、利用側が理解すべき依存関係は減りません。

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

• 1.1 から必読のリファレンス：component-data-flow
• 基本モデルとして、props を下方向に渡し、イベントを上方向に送ります。
• 真の双方向コンポーネントコントラクトに限り、v-model を使用します。
• 中間コンポーネントが共有依存関係を中継するだけの場合は、型付きのスコープ付き provide/inject を使用します。その前に、コンポーネントの境界を見直します。スコープと所有権については、データフローのリファレンスを参照してください。
• 必要に応じて defineProps、defineEmits、InjectionKey を使い、コントラクトを明示的かつ型付きに保ちます。

コンポーザブル

• 1.1 から必読のリファレンス：composables
• コードの整理に役立つ単一箇所でのみ使用するワークフローも含め、まとまりのある機能を組み合わせて、状態を伴う大規模な処理を構成します。単純なコンポーネントローカルのロジックはそのままローカルに置き、純粋な計算には通常の関数を使います。
• 実装の所有者と公開ファサードを区別します。コーディネーターは機能同士をつなぎ、機能をまたぐ処理を実装しますが、それらすべての実装を含めたり、内部機能をすべて再エクスポートしたりするべきではありません。
• 利用側に必要な状態とアクションを返します。利用側が互いに無関係な内部機能のグループを必要とする場合は、その利用側の責務も見直します。利用側が無効化を手動で起こさなくても現在の値を読み取れるよう、リアクティブな内部管理をカプセル化します。
• DOM とのやり取りとクリーンアップは、それらを所有する UI またはコンポーザブルに置きます。他の機能が必要とする明示的な連携は維持します。たとえば、保存前に保留中の下書きを確定する処理などです。

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 の構成とテンプレートのルールに従っている。
• 境界に関するレビューの両面に合格している：分離可能な重要な責務が一つの実装に集中したままになっておらず、また、抽出した単位が単に転送するだけでなく、有用な複雑さを隠蔽している。
• 公開契約に型が付与され、内部実装が隠蔽されている。代表的なローカル変更をコード内で追跡し、無関係な転送処理の変更を伴わずに、担当する UI／ワークフローと正当な調整の範囲内で完結することを確認する。
• 状態の所有者と有効期間が明確である。共有する利用側は意図した同じインスタンスを使い、独立したインスタンスは独立したままで、所有者の終了時に副作用がクリーンアップされる。
• リファクタリングによって、保留中の処理や機能をまたぐ操作も含め、既存の動作が維持されている。プロジェクトに適用されるテストを使用する。API やファイルサイズが小さくなっただけでは、成功の根拠にならない。
• オプション機能は、要件で必要とされる場合に限り使用している。
• パフォーマンスの変更は、機能が完成した後にのみ適用している。