vue-best-practices · ejirocodes — Claude Code skill: Vue 3 TypeScript
vue-best-practices — a skill for Claude and other agents that steers Vue 3 TypeScript work: component patterns, Volar setup and Pinia mocks in tests.
MIT 301 installs ★ 6 updated 2026-06-25
npx skills add ejirocodes/agent-skills --skill vue-best-practices -a claude-codeWhat vue-best-practices does
The skill hands the agent a working set of Vue 3 TypeScript patterns. Prop types come from ComponentProps in vue-component-type-helpers; models get declared with defineModel and required; template refs go through useTemplateRef. Behind that sit reference files typescript.md, volar.md, components.md, tooling.md and testing.md, with a table at the top saying which one fits the task.
Version details matter here. Reactive props destructure, useTemplateRef and useId are written for Vue 3.5, and createSpy has been mandatory in createTestingPinia since @pinia/testing 1.0. Put strictTemplates in tsconfig.app.json rather than the root tsconfig, or template checking stays quiet. Neovim users running Volar 3.0 should switch from ts_ls to vtsls.
A mistakes section covers the usual traps: reaching for InstanceType<typeof Component>['$props'] instead of ComponentProps, and deep: true on big structures where numeric depth is enough.
What it helps with
- pull prop types out of a wrapped component
- wire up
strictTemplatesso templates get type-checked - move a component from
withDefaultsto reactive props destructure - mock a Pinia store in a component test with
createTestingPinia - stop SSR hydration mismatches caused by random ids
Example prompts for the agent
- Refactor
UserCard.vuefor Vue 3.5: extract its props withComponentPropsand dropwithDefaults. - Our
createTestingPiniasetup fails inCartList.spec.ts— fix the store mock. - Set up
strictTemplatesintsconfig.app.jsonand explain whatvueCompilerOptionsbuys us.
How to install vue-best-practices
1Skills CLI (Vercel)
npx skills add ejirocodes/agent-skills --skill vue-best-practices -a claude-code2Manually: put the files in place
~/.claude/skills/vue-best-practices/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vue-best-practices/
1Skills CLI (Vercel)
npx skills add ejirocodes/agent-skills --skill vue-best-practices -a codex2Manually: put the files in place
.agents/skills/vue-best-practices/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ejirocodes/agent-skills --skill vue-best-practices -a cursor2Manually: put the files in place
.cursor/skills/vue-best-practices/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ejirocodes/agent-skills vue/skills/vue-best-practices2Manually: put the files in place
.github/skills/vue-best-practices/SKILL.md1Skills CLI (Vercel)
npx skills add ejirocodes/agent-skills --skill vue-best-practices -a gemini-cli2Platform CLI
gemini skills install https://github.com/ejirocodes/agent-skills --path vue/skills/vue-best-practicesManually: put the files in place
.devin/skills/vue-best-practices/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ejirocodes/agent-skills --skill vue-best-practices -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about vue-best-practices
How do I install vue-best-practices in Claude Code?
Run npx skills add ejirocodes/agent-skills --skill vue-best-practices -a claude-code. The skill lands at ~/.claude/skills/vue-best-practices/SKILL.md.
What does vue-best-practices do?
It gives the agent Vue 3 TypeScript patterns: prop extraction, defineModel, useTemplateRef, Volar configuration and Pinia test mocks.
Which Vue version do the examples target?
Reactive props destructure, useTemplateRef and useId are written for Vue 3.5. In tests, createSpy is required from @pinia/testing 1.0 onward.
Source text
SKILL.md · MIT
---
name: vue-best-practices
description: "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."
license: MIT
metadata:
author: ejirocodes
version: '1.0.0'
---
# Vue 3 Best Practices
## Quick Reference
| Topic | When to Use | Reference |
|-------|-------------|-----------|
| **TypeScript** | Props extraction, generic components, useTemplateRef, JSDoc, reactive props destructure | [typescript.md](references/typescript.md) |
| **Volar** | IDE config, strictTemplates, CSS modules, directive comments, Volar 3.0 migration | [volar.md](references/volar.md) |
| **Components** | defineModel, deep watch, onWatcherCleanup, useId, deferred teleport | [components.md](references/components.md) |
| **Tooling** | moduleResolution, HMR SSR, duplicate plugin detection | [tooling.md](references/tooling.md) |
| **Testing** | Pinia store mocking, setup stores, Vue Router typed params | [testing.md](references/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
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
© ejirocodes · MIT · ejirocodes/agent-skills
Similar skills
All skills for Frontend and UI →vue-best-practices by other authors comes first.