Vue Best Practices

Overview

Comprehensive performance optimization guide for Vue 3 and Nuxt applications, containing 40+ rules across 8 categories. Rules are prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Vue 3 components or Nuxt pages
• Implementing data fetching (client or server-side)
• Reviewing code for performance issues
• Refactoring existing Vue/Nuxt code
• Optimizing bundle size or load times

Priority-Ordered Guidelines

Rules are prioritized by impact:

Priority	Category	Impact
1	Eliminating Waterfalls	CRITICAL
2	Bundle Size Optimization	CRITICAL
3	Server-Side Performance	HIGH
4	Reactivity Optimization	MEDIUM-HIGH
5	Re-render Optimization	MEDIUM
6	Rendering Performance	MEDIUM
7	JavaScript Performance	LOW-MEDIUM
8	Advanced Patterns	LOW

Quick Reference

Critical Patterns (Apply First)

Eliminate Waterfalls:

• Defer await until needed (move into branches)
• Use Promise.all() for independent async operations
• Start promises early, await late
• Use Nuxt useAsyncData with lazy option for parallel fetching
• Use <Suspense> boundaries to stream content

Reduce Bundle Size:

• Avoid barrel file imports (import directly from source)
• Use defineAsyncComponent for heavy components
• Defer non-critical third-party libraries
• Use Vite's dynamic import for code splitting
• Consider petite-vue for progressive enhancement

High-Impact Server Patterns

• Avoid cross-request state pollution in SSR
• Create new app instance per request
• Use Pinia with SSR-safe patterns
• Parallelize data fetching with component composition
• Minimize serialization at SSR boundaries

Medium-Impact Reactivity Patterns

• Use ref() as primary API over reactive()
• Use shallowRef() for large immutable data
• Apply markRaw() for non-reactive data
• Use toRef()/toRefs() for safe destructuring
• Leverage computed stability (Vue 3.4+)

Re-render Patterns

• Use v-once for static content
• Use v-memo for conditional update skipping
• Keep props stable to prevent child updates
• Avoid unnecessary component abstractions
• Use derived state in watchers

Rendering Patterns

• Virtualize large lists with vue-virtual-scroller
• Use content-visibility: auto for long lists
• Apply <KeepAlive> for component caching
• Use <Teleport> for portal rendering
• Prefer v-if over v-show for heavy components

JavaScript Patterns

• Batch DOM CSS changes via classes
• Build index maps for repeated lookups
• Cache repeated function calls
• Use toSorted() instead of sort() for immutability
• Early return from functions

References

Full documentation with code examples is available in:

• references/vue-performance-guidelines.md - Complete guide with all patterns
• references/rules/ - Individual rule files organized by category

To look up a specific pattern, grep the rules directory:

grep -l "suspense" references/rules/
grep -l "async-component" references/rules/
grep -l "shallowRef" references/rules/

Rule Categories in references/rules/

• async-* - Waterfall elimination patterns
• bundle-* - Bundle size optimization
• server-* - Server-side performance
• reactivity-* - Vue reactivity patterns
• rerender-* - Re-render optimization
• rendering-* - DOM rendering performance
• js-* - JavaScript micro-optimizations
• advanced-* - Advanced patterns