Vue 3 Best Practices

Quick Reference

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

1. Using InstanceType<typeof Component>['$props'] – Use ComponentProps instead
2. Missing createSpy in createTestingPinia – Required in @pinia/testing 1.0+
3. Using withDefaults with union types – Use Reactive Props Destructure
4. strictTemplates in wrong tsconfig – Add to tsconfig.app.json, not root
5. ts_ls with Volar 3.0 – Use vtsls instead (Neovim)
6. deep: true on large structures – Use numeric depth for performance
7. Watching destructured props directly – Wrap in getter: watch(() => count, ...)
8. Random IDs in SSR – Use useId() for hydration-safe IDs