9.0 KiB
9.0 KiB
| description | applyTo |
|---|---|
| VueJS 3開発標準とComposition API及びTypeScriptでのベストプラクティス | **/*.vue, **/*.ts, **/*.js, **/*.scss |
VueJS 3 開発指示書
Composition API、TypeScript、モダンベストプラクティスを使用した高品質VueJS 3アプリケーション構築のための指示書。
プロジェクトコンテキスト
- Vue 3.xとComposition APIをデフォルトとして使用
- 型安全性のためのTypeScript
<script setup>構文を使用した単一ファイルコンポーネント（.vue）- モダンビルドツール（Vite推奨）
- アプリケーション状態管理のためのPinia
- 公式Vueスタイルガイドとベストプラクティス
開発標準
アーキテクチャ
- Options APIよりもComposition API（
setup関数とcomposables）を優先 - スケーラビリティのためにコンポーネントとcomposablesを機能またはドメインで整理
- UI重視コンポーネント（プレゼンテーション）とロジック重視コンポーネント（コンテナ）を分離
- 再利用可能なロジックを
composables/ディレクトリのcomposable関数に抽出 - 明確に定義されたアクション、状態、ゲッターでドメイン別にストアモジュール（Pinia）を構造化
TypeScript統合
- 最大型安全性のために
tsconfig.jsonでstrictモードを有効化 defineComponentまたはdefinePropsとdefineEmitsを使った<script setup lang="ts">を使用- 型付きpropsとデフォルト値に
PropType<T>を活用 - 複雑なpropと状態の形にはインターフェースまたは型エイリアスを使用
- イベントハンドラー、refs、
useRoute/useRouterフックの型を定義 - 適用可能な場所でジェネリックコンポーネントとcomposablesを実装
コンポーネント設計
- コンポーネントに対して単一責任原則を遵守
- コンポーネント名にはPascalCase、ファイル名にはkebab-caseを使用
- コンポーネントを小さく、一つの関心事に焦点を当てる
- 簡潔性とパフォーマンスのために
<script setup>構文を使用 - TypeScriptでpropsを検証；必要な場合のみランタイムチェックを使用
- 柔軟な構成のためにslotsとscoped slotsを優先
状態管理
- グローバル状態にはPiniaを使用：
defineStoreでストアを定義 - 単純なローカル状態には
setup内でrefとreactiveを使用 - 派生状態には
computedを使用 - 複雑な構造のために状態を正規化
- 非同期ロジックにはPiniaストアのアクションを使用
- 永続化やデバッグのためにストアプラグインを活用
Composition APIパターン
- 共有ロジック（例：
useFetch、useAuth）のために再利用可能なcomposablesを作成 - 精密な依存関係リストで
watchとwatchEffectを使用 onUnmountedまたはwatchクリーンアップコールバックでサイドエフェクトをクリーンアップ- 深い依存関係注入には
provide/injectを控えめに使用 useAsyncDataまたはサードパーティデータユーティリティ（Vue Query）を使用
スタイリング
- コンポーネントレベルスタイルまたはCSSモジュールには
<style scoped>を使用 - 高速スタイリングのためにユーティリティファーストフレームワーク（Tailwind CSS）を検討
- クラス命名にはBEMまたは機能的CSS規約に従う
- テーマとデザイントークンにはCSSカスタムプロパティを活用
- CSS GridとFlexboxでモバイルファースト、レスポンシブデザインを実装
- スタイルがアクセシブル（コントラスト、フォーカス状態）であることを確保
パフォーマンス最適化
- 動的インポートと
defineAsyncComponentでコンポーネントを遅延ロード - 非同期コンポーネント読み込みフォールバックに
<Suspense>を使用 - 静的または変更頻度の低い要素に
v-onceとv-memoを適用 - Vue DevToolsパフォーマンスタブでプロファイル
- 不要なウォッチャーを避ける；可能な場合は
computedを優先 - 未使用コードをツリーシェイクし、Viteの最適化機能を活用
データフェッチング
useFetch（Nuxt）またはVue Queryのようなライブラリのcomposablesを使用- ローディング、エラー、成功状態を明示的に処理
- コンポーネントアンマウントまたはパラメータ変更時に古いリクエストをキャンセル
- 失敗時のロールバックでオプティミスティック更新を実装
- レスポンスをキャッシュし、バックグラウンド再検証を使用
エラーハンドリング
- キャッチされていないエラーにはグローバルエラーハンドラー（
app.config.errorHandler）を使用 - リスキーなロジックを
try/catchでラップ；ユーザーフレンドリーなメッセージを提供 - ローカル境界のためにコンポーネントで
errorCapturedフックを使用 - フォールバックUIまたはエラーアラートを優雅に表示
- 外部サービス（Sentry、LogRocket）にエラーをログ記録
フォームと検証
- 宣言的検証にはVeeValidateや@vueuse/formのようなライブラリを使用
- 制御された
v-modelバインディングでフォームを構築 - パフォーマンスのためにデバウンシングでblurまたはinput時に検証
- composablesでファイルアップロードと複雑な多段階フォームを処理
- アクセシブルなラベリング、エラー告知、フォーカス管理を確保
ルーティング
createRouterとcreateWebHistoryでVue Router 4を使用- ネストされたルートとルートレベルコード分割を実装
- ナビゲーションガード（
beforeEnter、beforeEach）でルートを保護 - プログラム的ナビゲーションのために
setupでuseRouteとuseRouterを使用 - クエリパラメータと動的セグメントを適切に管理
- ルートメタフィールドを通じてブレッドクラムデータを実装
テスト
- Vue Test UtilsとJestで単体テストを記述
- 実装詳細ではなく動作に焦点を当てる
- コンポーネント分離のために
mountとshallowMountを使用 - 必要に応じてグローバルプラグイン（router、Pinia）をモック
- CypressまたはPlaywrightでエンドツーエンドテストを追加
- axe-core統合を使用してアクセシビリティをテスト
セキュリティ
v-htmlの使用を避ける；HTMLインプットを厳格に無害化- XSSとインジェクション攻撃を軽減するためにCSPヘッダーを使用
- テンプレートとディレクティブでデータを検証・エスケープ
- すべてのAPIリクエストにHTTPSを使用
localStorageではなくHTTP専用クッキーに機密トークンを保存
アクセシビリティ
- セマンティックHTML要素とARIA属性を使用
- モーダルと動的コンテンツのフォーカス管理
- インタラクティブコンポーネントにキーボードナビゲーションを提供
- 画像とアイコンに意味のある
altテキストを追加 - カラーコントラストがWCAG AA標準を満たすことを確保
実装プロセス
- コンポーネントとcomposableアーキテクチャを計画
- Vue 3とTypeScriptでViteプロジェクトを初期化
- Piniaストアとcomposablesを定義
- コアUIコンポーネントとレイアウトを作成
- ルーティングとナビゲーションを統合
- データフェッチングと状態ロジックを実装
- 検証とエラー状態を持つフォームを構築
- グローバルエラーハンドリングとフォールバックUIを追加
- 単体テストとE2Eテストを追加
- パフォーマンスとバンドルサイズを最適化
- アクセシビリティコンプライアンスを確保
- コンポーネント、composables、ストアを文書化
追加ガイドライン
- Vueの公式スタイルガイド（vuejs.org/style-guide）に従う
- コード一貫性のためにESLint（
plugin:vue/vue3-recommendedと）とPrettierを使用 - 意味のあるコミットメッセージを書き、クリーンなgit履歴を維持
- 依存関係を最新に保ち、脆弱性を監査
- JSDoc/TSDocで複雑なロジックを文書化
- デバッグとプロファイリングにVue DevToolsを使用
共通パターン
- 柔軟なUIのためのレンダーレスコンポーネントとscoped slots
- provide/injectを使用したコンパウンドコンポーネント
- 横断的関心事のためのカスタムディレクティブ
- モーダルとオーバーレイのためのTeleport
- グローバルユーティリティ（i18n、アナリティクス）のためのプラグインシステム
- パラメータ化されたロジックのためのComposableファクトリー