Vue Best Practices

Comprehensive performance optimization guide for Vue.js applications (verified against the official Vue 3.5+ docs). Contains 18 rules across 5 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 - Prefer ref() as the primary reactivity API
• reactivity-avoid-destructure - Don't destructure reactive objects
• reactivity-toRefs - Use toRefs()/getters when destructuring is needed
• reactivity-shallowRef - Use shallowRef() for large non-reactive data
• reactivity-raw-values - Treat toRaw() as a narrow escape hatch

2. Component Performance (CRITICAL)

• component-async - Use defineAsyncComponent for heavy components
• component-keep-alive - Cache component state with KeepAlive
• component-v-memo - v-memo micro-optimization for 1000+ item lists
• component-v-once - Use v-once for static content
• component-functional - Keep stateless components simple

3. Computed & Watchers (HIGH)

• computed-cache - Use computed() for derived values, not methods
• computed-dependencies - Understand fine-grained per-property dependency tracking
• watch-deep-avoid - Avoid deep watchers on large objects

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 primitive keys in v-for
• template-avoid-v-if-v-for - Never use v-if and v-for on same element

5. Composition API Patterns (MEDIUM)

• composable-single-responsibility - One concern per composable
• composable-return-refs - Return refs, not reactive objects

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