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