Vue 3 Best Practices
Quick Reference
Topic When to Use Reference
TypeScript Props extraction, generic components, useTemplateRef, JSDoc, reactive props destructure typescript.md
Volar IDE config, strictTemplates, CSS modules, directive comments, Volar 3.0 migration volar.md
Components defineModel, deep watch, onWatcherCleanup, useId, deferred teleport components.md
Tooling moduleResolution, HMR SSR, duplicate plugin detection tooling.md
Testing Pinia store mocking, setup stores, Vue Router typed params testing.md
Essential Patterns
Extract Component Props
import type { ComponentProps } from 'vue-component-type-helpers' import MyButton from './MyButton.vue'
type Props = ComponentProps<typeof MyButton>
Reactive Props Destructure (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 with Required
// Returns Ref<Item> instead of Ref<Item | undefined> const model = defineModel<Item>({ required: true })
Deep Watch with Numeric Depth
// Vue 3.5+ - watch array mutations without full traversal watch(items, handler, { deep: 1 })
Pinia Store Test Setup
import { createTestingPinia } from '@pinia/testing' import { vi } from 'vitest'
mount(Component, { global: { plugins: [createTestingPinia({ createSpy: vi.fn })] } })
Common Mistakes
-
Using InstanceType<typeof Component>['$props']
-
Use ComponentProps instead
-
Missing createSpy in createTestingPinia - Required in @pinia/testing 1.0+
-
Using withDefaults with union types - Use Reactive Props Destructure
-
strictTemplates in wrong tsconfig - Add to tsconfig.app.json , not root
-
ts_ls with Volar 3.0 - Use vtsls instead (Neovim)
-
deep: true on large structures - Use numeric depth for performance
-
Watching destructured props directly - Wrap in getter: watch(() => count, ...)
-
Random IDs in SSR - Use useId() for hydration-safe IDs