Agent Skills: Vue 3 Best Practices

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

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