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

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 <script setup> 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