Vue 3 Best Practices

Comprehensive performance optimization and development guide for Vue 3 applications. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Vue 3 components or composables
• Implementing reactive data and computed properties
• Reviewing code for performance issues
• Refactoring from Vue 2 to Vue 3
• Optimizing bundle size or load times
• Working with state management (Pinia/Vuex)
• Implementing async operations in components

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Reactivity Performance	CRITICAL	reactivity-
2	Component Optimization	CRITICAL	component-
3	Bundle Size & Loading	HIGH	bundle-
4	Composition API	MEDIUM-HIGH	composition-
5	Template Performance	MEDIUM	template-
6	State Management	MEDIUM	state-
7	Lifecycle Optimization	LOW-MEDIUM	lifecycle-
8	Advanced Patterns	LOW	advanced-

Quick Reference

1. Reactivity Performance (CRITICAL)

• reactivity-ref-vs-reactive - Use ref for primitives, reactive for objects
• reactivity-shallow-ref - Use shallowRef for large immutable objects
• reactivity-computed-caching - Leverage computed property caching
• reactivity-watch-vs-watcheffect - Choose appropriate watcher
• reactivity-unref-performance - Minimize unref calls in hot paths
• reactivity-readonly-immutable - Use readonly for immutable data

2. Component Optimization (CRITICAL)

• component-async-components - Use defineAsyncComponent for heavy components
• component-functional - Use functional components for simple presentational logic
• component-keep-alive - Cache expensive components with keep-alive
• component-lazy-hydration - Implement lazy hydration for non-critical components
• component-prop-validation - Use efficient prop validation
• component-emit-performance - Optimize event emissions

3. Bundle Size & Loading (HIGH)

• bundle-tree-shaking - Structure imports for optimal tree-shaking
• bundle-dynamic-imports - Use dynamic imports for code splitting
• bundle-plugin-imports - Use unplugin-auto-import for better DX
• bundle-lodash-imports - Import lodash functions individually
• bundle-moment-alternatives - Use day.js instead of moment.js
• bundle-icons-optimization - Optimize icon imports and usage

4. Composition API (MEDIUM-HIGH)

• composition-script-setup - Prefer for better performance
• composition-composables-reuse - Extract reusable logic into composables
• composition-provide-inject - Use provide/inject for dependency injection
• composition-expose-selectively - Expose only necessary properties
• composition-reactive-transform - Use reactive transform where appropriate
• composition-auto-import - Configure auto-imports for better DX

5. Template Performance (MEDIUM)

• template-v-once - Use v-once for static content
• template-v-memo - Use v-memo for expensive list rendering
• template-key-optimization - Optimize v-for keys for performance
• template-conditional-rendering - Choose v-if vs v-show appropriately
• template-slot-performance - Optimize slot usage and scoped slots
• template-directive-optimization - Create efficient custom directives

6. State Management (MEDIUM)

• state-pinia-optimization - Optimize Pinia store structure
• state-store-composition - Use store composition patterns
• state-persistence - Implement efficient state persistence
• state-normalization - Normalize complex state structures
• state-subscription - Optimize state subscriptions
• state-devtools - Configure devtools for debugging

7. Lifecycle Optimization (LOW-MEDIUM)

• lifecycle-cleanup - Properly cleanup resources in onUnmounted
• lifecycle-async-setup - Handle async operations in setup
• lifecycle-watchers-cleanup - Clean up watchers and effects
• lifecycle-dom-access - Access DOM safely in lifecycle hooks
• lifecycle-ssr-considerations - Handle SSR lifecycle differences

8. Advanced Patterns (LOW)

• advanced-teleport-usage - Use Teleport for portal patterns
• advanced-suspense-async - Implement Suspense with async components
• advanced-custom-renderer - Create custom renderers when needed
• advanced-compiler-macros - Use compiler macros effectively
• advanced-plugin-development - Develop efficient Vue plugins

Framework Integration

Vite Integration

• Utilize Vite's fast HMR and build optimizations
• Configure proper chunk splitting strategies
• Use Vite plugins for Vue-specific optimizations

TypeScript Integration

• Leverage Vue 3's improved TypeScript support
• Use proper type definitions for better DX
• Configure TypeScript for optimal build performance

Testing Integration

• Use Vue Test Utils with Composition API
• Implement efficient component testing strategies
• Optimize test performance and reliability

How to Use

Read individual rule files for detailed explanations and code examples:

rules/reactivity-ref-vs-reactive.md
rules/component-async-components.md
rules/composition-script-setup.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect Vue 3 code example with explanation
• Correct Vue 3 code example with explanation
• Performance impact and measurements
• Additional context and Vue 3-specific considerations

Migration from Vue 2

Special considerations for migrating from Vue 2:

• Composition API vs Options API patterns
• Reactivity system changes and optimizations
• Component definition and registration updates
• Event handling and lifecycle changes

Performance Monitoring

Tools and techniques for monitoring Vue 3 performance:

• Vue DevTools integration
• Performance profiling with browser tools
• Bundle analysis and optimization
• Runtime performance monitoring