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
1---2name: vue-best-practices3description: Vue 3 and Vue.js best practices for TypeScript, vue-tsc, Volar, and component patterns. Use when writing, reviewing, or refactoring Vue 3 components with TypeScript, configuring Volar/vueCompilerOptions, extracting component types, working with defineModel/withDefaults, setting up Pinia store tests, or debugging Vue tooling issues. Triggers on Vue components, props extraction, wrapper components, template type checking, strictTemplates, vueCompilerOptions, Volar 3, CSS modules, fallthrough attributes, defineModel, withDefaults, deep watch, vue-router typed params, Pinia mocking, HMR SSR, moduleResolution bundler, useTemplateRef, onWatcherCleanup, useId, generic components, reactive props destructure.4license: MIT5---67# Vue 3 Best Practices89## Quick Reference1011| Topic | When to Use | Reference |12|-------|-------------|-----------|13| **TypeScript** | Props extraction, generic components, useTemplateRef, JSDoc, reactive props destructure | [typescript.md](references/typescript.md) |14| **Volar** | IDE config, strictTemplates, CSS modules, directive comments, Volar 3.0 migration | [volar.md](references/volar.md) |15| **Components** | defineModel, deep watch, onWatcherCleanup, useId, deferred teleport | [components.md](references/components.md) |16| **Tooling** | moduleResolution, HMR SSR, duplicate plugin detection | [tooling.md](references/tooling.md) |17| **Testing** | Pinia store mocking, setup stores, Vue Router typed params | [testing.md](references/testing.md) |1819## Essential Patterns2021### Extract Component Props2223```typescript24import type { ComponentProps } from 'vue-component-type-helpers'25import MyButton from './MyButton.vue'2627type Props = ComponentProps<typeof MyButton>28```2930### Reactive Props Destructure (Vue 3.5+)3132```vue33<script setup lang="ts">34// Destructured props are reactive - preferred in Vue 3.5+35const { name, count = 0 } = defineProps<{ name: string; count?: number }>()36</script>37```3839### useTemplateRef (Vue 3.5+)4041```vue42<script setup lang="ts">43import { useTemplateRef, onMounted } from 'vue'4445const inputRef = useTemplateRef('input') // Auto-typed46onMounted(() => inputRef.value?.focus())47</script>48<template><input ref="input" /></template>49```5051### onWatcherCleanup (Vue 3.5+)5253```typescript54import { watch, onWatcherCleanup } from 'vue'5556watch(query, async (q) => {57 const controller = new AbortController()58 onWatcherCleanup(() => controller.abort())59 await fetch(`/api?q=${q}`, { signal: controller.signal })60})61```6263### defineModel with Required6465```typescript66// Returns Ref<Item> instead of Ref<Item | undefined>67const model = defineModel<Item>({ required: true })68```6970### Deep Watch with Numeric Depth7172```typescript73// Vue 3.5+ - watch array mutations without full traversal74watch(items, handler, { deep: 1 })75```7677### Pinia Store Test Setup7879```typescript80import { createTestingPinia } from '@pinia/testing'81import { vi } from 'vitest'8283mount(Component, {84 global: {85 plugins: [createTestingPinia({ createSpy: vi.fn })]86 }87})88```8990## Common Mistakes91921. **Using `InstanceType<typeof Component>['$props']`** - Use `ComponentProps` instead932. **Missing `createSpy` in createTestingPinia** - Required in @pinia/testing 1.0+943. **Using `withDefaults` with union types** - Use Reactive Props Destructure954. **`strictTemplates` in wrong tsconfig** - Add to `tsconfig.app.json`, not root965. **ts_ls with Volar 3.0** - Use vtsls instead (Neovim)976. **`deep: true` on large structures** - Use numeric depth for performance987. **Watching destructured props directly** - Wrap in getter: `watch(() => count, ...)`998. **Random IDs in SSR** - Use `useId()` for hydration-safe IDs
ejirocodes