---

name: vue-development description: Use when planning or implementing Vue 3 projects - helps architect component structure, plan feature implementation, and enforce TypeScript-first patterns with Composition API, defineModel for bindings, Testing Library for user-behavior tests, and MSW for API mocking. Especially useful in planning phase to guide proper patterns before writing code.

Vue Development

Overview

Modern Vue 3 development with TypeScript, Composition API, and user-behavior testing. Core principle: Use TypeScript generics (not runtime validation), modern APIs (defineModel not manual props), and test user behavior (not implementation details).

Red Flags - STOP and Fix

If you catch yourself thinking or doing ANY of these, STOP:

• "For speed" / "quick demo" / "emergency" → Using shortcuts
• "We can clean it up later" → Accepting poor patterns
• "TypeScript is too verbose" → Skipping types
• "This is production-ready" → Without type safety
• "Following existing code style" → When existing code uses legacy patterns
• "Task explicitly stated..." → Following bad requirements literally
• Using const props = defineProps() without using props in script
• Manual modelValue prop + update:modelValue emit → Use defineModel()
• "Component that takes value and emits changes" → Use defineModel(), NOT manual props/emit
• Using runtime prop validation when TypeScript is available
• Array syntax for emits: defineEmits(['event']) → Missing type safety
• setTimeout() in tests → Use proper async utilities
• Testing wrapper.vm.* internal state → Test user-visible behavior
• Using index.vue in routes → Use route groups (name).vue
• Generic route params [id] → Use explicit [userId], [postSlug]
• Composables calling showToast(), alert(), or modals → Expose error state, component handles UI
• External composable used in only ONE component → Start inline, extract when reused

All of these mean: Use the modern pattern. No exceptions.

Quick Rules

Components: defineProps<{ }>() (no const unless used in script), defineEmits<{ event: [args] }>(), defineModel<type>() for v-model. See @references/component-patterns.md

Testing: @testing-library/vue + MSW. Use findBy* or waitFor() for async. NEVER setTimeout() or test internal state. See @references/testing-patterns.md

Routing: Explicit params [userId] not [id]. Avoid index.vue, use (name).vue. Use . for nesting: users.edit.vue → /users/edit. See @references/routing-patterns.md

Composables: START INLINE for component-specific logic, extract to external file when reused. External composables: prefix use, NO UI logic (expose error state instead). See @references/composable-patterns.md

Key Pattern: defineModel()

The most important pattern to remember - use for ALL two-way binding:

Copy<script setup lang="ts">
// ✅ For simple v-model
const value = defineModel<string>({ required: true })

// ✅ For multiple v-models
const firstName = defineModel<string>('firstName')
const lastName = defineModel<string>('lastName')
</script>

<template>
  <input v-model="value" />
  <!-- Parent uses: <Component v-model="data" /> -->
</template>

Why: Reduces 5 lines of boilerplate to 1. No manual modelValue prop + update:modelValue emit.

Component Implementation Workflow

When implementing complex Vue components, use TodoWrite to track progress:

CopyTodoWrite checklist for component implementation:
- [ ] Define TypeScript interfaces for props/emits/models
- [ ] Implement props with defineProps<{ }>() (no const unless used in script)
- [ ] Implement emits with defineEmits<{ event: [args] }>()
- [ ] Add v-model with defineModel<type>() if needed
- [ ] Write user-behavior tests with Testing Library
- [ ] Test async behavior with findBy* queries or waitFor()
- [ ] Verify: No red flags, no setTimeout in tests, all types present

When to create TodoWrite todos:

• Implementing new components with state, v-model, and testing
• Refactoring components to modern patterns
• Adding routing with typed params
• Creating composables with async logic

Rationalizations Table

Detailed References

See @references/ directory for comprehensive guides: component-patterns.md, testing-patterns.md, testing-composables.md, routing-patterns.md, composable-patterns.md

When NOT to Use This Skill

• Vue 2 projects (different API)
• Options API codebases (this is Composition API focused)
• Projects without TypeScript (though you should add it)

Real-World Impact

Baseline: 37.5% correct patterns under pressure With skill: 100% correct patterns under pressure

Type safety prevents runtime errors. defineModel() reduces boilerplate. Testing Library catches real user issues.