vue-best-practices

name	vue-best-practices
description	Comprehensive Vue 3 development best practices, TypeScript configuration, tooling troubleshooting, testing patterns, and composition API gotchas. Covers vue-tsc, Volar, Vite configuration, Vue Router typing, component testing, reactivity patterns, and SFC features. Use when working with Vue 3 + TypeScript projects, debugging build errors, writing tests, or following best practices.
license	MIT
metadata	{"author":"hyf0","version":"5.0.0"}

Vue Best Practices

Comprehensive development guidelines, TypeScript configuration, and best practices for Vue 3 applications.

When to Apply

• Setting up or configuring Vue 3 + TypeScript projects
• Debugging type checking issues with vue-tsc
• Fixing IDE/editor integration with Volar
• Configuring Vite for Vue projects
• Working with Vue Router typed routes
• Writing component tests with Vitest
• Using Composition API patterns
• Working with defineModel, defineProps, defineExpose
• Writing reusable composables

---

Capability Rules

Rules that enable AI to solve problems it cannot solve without the skill.

Type Checking

Rule	Impact	Description
vue-tsc-strict-templates	HIGH	Enable strict template checking to catch undefined components
vue-define-model-generics	HIGH	Fix vue-tsc errors when using defineModel with generic components

vueCompilerOptions Settings

Rule	Impact	Description
fallthrough-attributes	HIGH	Type-check fallthrough attributes on wrapper components
strict-css-modules	MEDIUM	Catch typos in CSS module class names at compile time
data-attributes-config	MEDIUM	Allow data-* attributes with strictTemplates enabled

Tooling & Configuration

Rule	Impact	Description
vue-tsc-typescript-compatibility	HIGH	Fix vue-tsc and TypeScript version incompatibility issues
volar-3-breaking-changes	HIGH	Fix editor integration after Volar/vue-language-server 3.0 upgrade
module-resolution-bundler	HIGH	Fix "Cannot find module" errors after @vue/tsconfig upgrade
unplugin-auto-import-conflicts	HIGH	Fix component types resolving as any with unplugin conflicts
codeactions-save-performance	HIGH	Fix 30-60 second save delays in large Vue projects

Vite Configuration

Rule	Impact	Description
path-alias-vue-sfc	HIGH	Fix resolve.alias failures in Vue SFC files
duplicate-plugin-detection	MEDIUM	Detect and fix duplicate Vue plugin registration

Component Patterns

Rule	Impact	Description
use-template-ref-generics	MEDIUM	Fix incorrect type inference for refs to generic components
define-model-update-event	MEDIUM	Fix runtime errors from unexpected undefined in model updates
with-defaults-union-types	MEDIUM	Fix incorrect default value behavior with union type props
verbatim-module-syntax	MEDIUM	Fix Vite dev server errors with type-only imports
deep-watch-numeric	MEDIUM	Enable efficient array mutation watching with Vue 3.5+ numeric deep

Template Patterns

Rule	Impact	Description
vue-directive-comments	HIGH	Control template type checking with @vue-ignore, @vue-skip directives

SFC Patterns

Rule	Impact	Description
script-setup-jsdoc	MEDIUM	Add JSDoc documentation to script setup components

Vue Router

Rule	Impact	Description
vue-router-typed-params	MEDIUM	Fix route params type narrowing with unplugin-vue-router

Testing Patterns

Rule	Impact	Description
teleport-testing	HIGH	Test teleported content (modals, tooltips)

TypeScript Patterns

Rule	Impact	Description
vueuse-emits-conflict	MEDIUM	Fix $emit type conflicts with VueUse element composables

---

Efficiency Rules

Rules that help AI solve problems more effectively and consistently.

Vite Configuration

Rule	Impact	Description
runtime-env-variables	HIGH	Implement runtime environment variables for multi-env deployments
hmr-vue-ssr	MEDIUM	Fix HMR issues in Vue SSR applications

Component Patterns

Rule	Impact	Description
define-expose-types	MEDIUM	Fix "Property does not exist" errors when accessing exposed methods
provide-inject-types	MEDIUM	Enable type-safe dependency injection with InjectionKey

Vue Router

Rule	Impact	Description
route-meta-types	HIGH	Extend RouteMeta interface for type-safe metadata
scroll-behavior-types	MEDIUM	Properly type scrollBehavior function
dynamic-routes-typing	MEDIUM	Type-safe dynamic route configuration

Testing Patterns

Rule	Impact	Description
suspense-testing	HIGH	Test async components with Suspense properly
pinia-store-mocking	HIGH	Mock Pinia stores correctly with Vitest
router-mocking	HIGH	Mock Vue Router with useRoute and useRouter
vue-test-utils-types	MEDIUM	Fix wrapper.vm property access types in Vue Test Utils

Composition API Patterns

Rule	Impact	Description
reactive-destructuring	HIGH	Avoid reactivity loss when destructuring reactive objects
composable-cleanup	HIGH	Prevent memory leaks in composables with proper cleanup
ref-unwrapping	MEDIUM	Understand ref auto-unwrapping in reactive objects
watcheffect-tracking	MEDIUM	Fix conditional dependency tracking in watchEffect

SFC Patterns

Rule	Impact	Description
script-setup-patterns	HIGH	Best practices for script setup syntax
css-v-bind	MEDIUM	Safely use reactive values in CSS

TypeScript Patterns

Rule	Impact	Description
component-type-helpers	HIGH	Extract component prop and emit types
event-handler-typing	MEDIUM	Type event handlers correctly

---

Reference

• Vue Language Tools
• Vue 3 Documentation
• Vite Documentation
• Vue Router
• Vue Test Utils
• VueUse