Vue Best Practices

Comprehensive performance optimization guide for Vue.js applications. Contains 40+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• •Writing new Vue components
• •Implementing reactive state and computed properties
• •Reviewing code for performance issues
• •Refactoring existing Vue code
• •Optimizing rendering and re-renders
• •Working with Composition API or Options API

Rule Categories by Priority

Quick Reference

1. Reactivity Fundamentals (CRITICAL)

• •reactivity-ref-vs-reactive - Use ref() for primitives, reactive() for objects
• •reactivity-avoid-destructure - Don't destructure reactive objects
• •reactivity-toRefs - Use toRefs() when destructuring is needed
• •reactivity-shallowRef - Use shallowRef() for large non-reactive data
• •reactivity-raw-values - Use toRaw() for read-only operations on large data

2. Component Performance (CRITICAL)

• •component-v-once - Use v-once for static content
• •component-v-memo - Use v-memo for expensive list items
• •component-async - Use defineAsyncComponent for heavy components
• •component-keep-alive - Cache component state with KeepAlive
• •component-functional - Prefer functional components for stateless UI

3. Computed & Watchers (HIGH)

• •computed-cache - Use computed() for derived values, not methods
• •computed-getter-only - Avoid setters in computed when possible
• •computed-dependencies - Minimize computed dependencies
• •watch-immediate - Avoid immediate watchers, use computed instead
• •watch-deep-avoid - Avoid deep watchers on large objects
• •watch-cleanup - Always cleanup async watchers

4. Template Optimization (MEDIUM-HIGH)

• •template-v-show-vs-if - v-show for frequent toggles, v-if for rare
• •template-key-attribute - Always use unique keys in v-for
• •template-avoid-v-if-v-for - Never use v-if and v-for on same element
• •template-static-hoisting - Let compiler hoist static content
• •template-event-modifiers - Use event modifiers instead of JS handlers

5. Composition API Patterns (MEDIUM)

• •composable-single-responsibility - One concern per composable
• •composable-return-refs - Return refs, not reactive objects
• •composable-cleanup - Handle cleanup in composables
• •composable-lazy-init - Lazy initialize expensive resources
• •composable-provide-inject - Use provide/inject for deep prop drilling

6. State Management (MEDIUM)

• •state-pinia-stores - Split stores by domain
• •state-getters - Use getters for computed state
• •state-actions-mutations - Keep mutations simple, logic in actions
• •state-subscription-cleanup - Cleanup store subscriptions

7. Async & Data Fetching (LOW-MEDIUM)

• •async-suspense - Use Suspense for async component loading
• •async-error-boundaries - Handle async errors gracefully
• •async-stale-while-revalidate - Implement SWR pattern for data fetching
• •async-abort-controller - Cancel pending requests on unmount

8. Advanced Patterns (LOW)

• •advanced-custom-directives - Create directives for DOM manipulation
• •advanced-render-functions - Use render functions for dynamic templates
• •advanced-teleport - Use Teleport for modals and overlays
• •advanced-transition-groups - Optimize list transitions

How to Use

Read individual rule files for detailed explanations and code examples:

rules/reactivity-ref-vs-reactive.md
rules/component-v-memo.md
rules/_sections.md

Each rule file contains:

• •Brief explanation of why it matters
• •Incorrect code example with explanation
• •Correct code example with explanation
• •Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md