vue-best-practices

Original：🇺🇸 English

Translated

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.

3installs

Sourceejirocodes/agent-skills

Added on2026-05-17

NPX Install

npx skill4agent add ejirocodes/agent-skills vue-best-practices

SKILL.md Content

View Translation Comparison →

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

typescript

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

type Props = ComponentProps<typeof MyButton>

Reactive Props Destructure (Vue 3.5+)

vue

<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+)

vue

<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+)

typescript

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

typescript

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

Deep Watch with Numeric Depth

typescript

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

Pinia Store Test Setup

typescript

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

vue-best-practices

NPX Install

Tags

SKILL.md Content

Vue 3 Best Practices

Quick Reference

Essential Patterns

Extract Component Props

Reactive Props Destructure (Vue 3.5+)

useTemplateRef (Vue 3.5+)

onWatcherCleanup (Vue 3.5+)

defineModel with Required

Deep Watch with Numeric Depth

Pinia Store Test Setup

Common Mistakes