vue-best-practices

Vue 3 のベストプラクティス

クイックリファレンス

トピック	使用する場面	リファレンス
TypeScript	Props の抽出、ジェネリックコンポーネント、useTemplateRef、JSDoc、リアクティブな props の分割代入	typescript.md
Volar	IDE の設定、strictTemplates、CSS モジュール、ディレクティブコメント、Volar 3.0 への移行	volar.md
コンポーネント	defineModel、ディープウォッチ、onWatcherCleanup、useId、遅延テレポート	components.md
ツール	moduleResolution、HMR SSR、プラグインの重複検出	tooling.md
テスト	Pinia ストアのモック、セットアップストア、Vue Router の型付きパラメーター	testing.md

基本的なパターン

コンポーネントの Props を抽出する

import type { ComponentProps } from 'vue-component-type-helpers'
import MyButton from './MyButton.vue'

type Props = ComponentProps<typeof MyButton>

リアクティブな Props の分割代入（Vue 3.5+）

<script setup lang="ts">
// Destructured props are reactive - preferred in Vue 3.5+
const { name, count = 0 } = defineProps<{ name: string; count?: number }>()
</script>

useTemplateRef（Vue 3.5+）

<script setup lang="ts">
import { useTemplateRef, onMounted } from 'vue'

const inputRef = useTemplateRef('input')  // Auto-typed
onMounted(() => inputRef.value?.focus())
</script>
<template><input ref="input" /></template>

onWatcherCleanup（Vue 3.5+）

import { watch, onWatcherCleanup } from 'vue'

watch(query, async (q) => {
  const controller = new AbortController()
  onWatcherCleanup(() => controller.abort())
  await fetch(`/api?q=${q}`, { signal: controller.signal })
})

必須項目を指定した defineModel

// Returns Ref<Item> instead of Ref<Item | undefined>
const model = defineModel<Item>({ required: true })

数値の深さを指定したディープウォッチ

// Vue 3.5+ - watch array mutations without full traversal
watch(items, handler, { deep: 1 })

Pinia ストアのテスト設定

import { createTestingPinia } from '@pinia/testing'
import { vi } from 'vitest'

mount(Component, {
  global: {
    plugins: [createTestingPinia({ createSpy: vi.fn })]
  }
})

よくある間違い

1. InstanceType<typeof Component>['$props'] を使う - 代わりに ComponentProps を使います
2. createTestingPinia で createSpy を指定し忘れる - @pinia/testing 1.0+ では必須です
3. ユニオン型で withDefaults を使う - 代わりにリアクティブな Props の分割代入を使います
4. 誤った tsconfig で strictTemplates を指定する - ルートではなく tsconfig.app.json に追加します
5. Volar 3.0 で ts_ls を使う - 代わりに vtsls を使います（Neovim）
6. 大規模な構造で deep: true を使う - パフォーマンス向上のため、数値で深さを指定します
7. 分割代入した props を直接監視する - ゲッターでラップします：watch(() => count, ...)
8. SSR でランダムな ID を使う - ハイドレーションに安全な ID を生成するには useId() を使います