Vuejs Best Practices

Vue.js Best Practices

Comprehensive performance optimization guide for Vue 3 and Nuxt 3 applications. Contains 50+ rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Vue 3 components or Nuxt 3 pages
• Using Composition API and composables
• Implementing data fetching (client or server-side)
• Managing state with Pinia
• Reviewing code for performance issues
• Refactoring existing Vue/Nuxt code
• Optimizing bundle size or load times

Rule Categories by Priority

Quick Reference

1. Reactivity Optimization (CRITICAL)

• reactivity-shallowref - Use shallowRef for large objects that don't need deep reactivity
• reactivity-shallowreactive - Use shallowReactive for flat objects
• reactivity-computed-cache - Leverage computed for expensive calculations (auto-caching)
• reactivity-toraw - Use toRaw() when passing to external libraries
• reactivity-markraw - Use markRaw() for non-reactive objects (classes, third-party instances)
• reactivity-effectscope - Use effectScope() to batch cleanup of effects

2. Bundle Size Optimization (CRITICAL)

• bundle-tree-shaking - Import from 'vue' not internal packages (@vue/reactivity, @vue/runtime-core)
• bundle-async-components - Use defineAsyncComponent for heavy components
• bundle-dynamic-imports - Dynamic import() for route-level code splitting
• bundle-icon-imports - Import icons directly, avoid icon libraries barrel files
• bundle-lodash-es - Use lodash-es with specific imports
• bundle-analyze - Use rollup-plugin-visualizer to identify bloat
• bundle-external-cdn - Externalize large libraries to CDN when appropriate

3. Nuxt 3 Server Performance (HIGH)

• nuxt-usefetch - Use useFetch/useAsyncData for SSR-friendly data fetching
• nuxt-lazy-components - Prefix with Lazy for automatic lazy loading
• nuxt-payload-reduce - Minimize payload with pick/transform options
• nuxt-cache-route - Use routeRules for caching strategies
• nuxt-server-components - Use .server.vue for server-only components
• nuxt-prerender - Prerender static pages at build time
• nuxt-islands - Use Nuxt Islands for partial hydration
• nuxt-nitro-cache - Leverage Nitro caching for API routes

4. Component Design Patterns (HIGH)

• component-sfc-setup - Always use <script setup> syntax
• component-props-destructure - Use destructuring with defineProps for reactivity
• component-emits-typed - Always define emits with TypeScript
• component-slots-typed - Type slots with defineSlots
• component-expose - Use defineExpose sparingly, prefer props/emits
• component-v-once - Use v-once for static content
• component-v-memo - Use v-memo for list item optimization
• component-teleport - Use Teleport for modals/tooltips

5. Composition API Patterns (MEDIUM-HIGH)

• composable-naming - Prefix composables with 'use' (useAuth, useFetch)
• composable-return-object - Return object, not array, for better DX
• composable-cleanup - Always handle cleanup in onUnmounted
• composable-async - Handle async state properly (loading, error, data)
• composable-ssr-safe - Check import.meta.client for browser-only code
• composable-provide-inject - Use provide/inject with InjectionKey for type safety
• composable-vueuse - Leverage VueUse before writing custom composables

6. State Management - Pinia (MEDIUM-HIGH)

• pinia-setup-syntax - Prefer setup stores over options stores
• pinia-storetorefs - Use storeToRefs() to maintain reactivity
• pinia-actions-async - Use actions for async operations, not getters
• pinia-persist - Use pinia-plugin-persistedstate for persistence
• pinia-reset - Implement $reset for store cleanup
• pinia-subscribe - Use $subscribe for side effects
• pinia-ssr-hydration - Handle SSR hydration properly in Nuxt

7. Rendering Performance (MEDIUM)

• rendering-v-show-v-if - v-show for frequent toggles, v-if for rare conditions
• rendering-key-attribute - Always use unique :key in v-for (avoid index as key)
• rendering-virtual-scroll - Use virtual scrolling for long lists (100+ items)
• rendering-keep-alive - Cache component instances with KeepAlive
• rendering-suspense - Use Suspense for async component loading states

8. TypeScript Integration (MEDIUM)

• typescript-props-interface - Define props with interface, not type
• typescript-ref-type - Explicitly type refs: ref<string>('')
• typescript-template-ref - Type template refs: ref<HTMLInputElement | null>(null)
• typescript-component-type - Use ComponentPublicInstance for component refs
• typescript-generic-components - Use generic components for reusable patterns
• typescript-strict-inject - Use InjectionKey for type-safe provide/inject
• typescript-event-handlers - Type event handlers properly

9. Testing Patterns (LOW-MEDIUM)

• testing-vitest - Use Vitest for unit testing (Vue ecosystem native)
• testing-vue-test-utils - Use @vue/test-utils for component testing
• testing-composables - Test composables in isolation
• testing-pinia - Use createTestingPinia for store testing
• testing-msw - Use MSW for API mocking
• testing-playwright - Use Playwright for E2E with Nuxt

10. Advanced Patterns (LOW)

• advanced-render-function - Use render functions for dynamic component generation
• advanced-custom-directive - Create custom directives for DOM manipulation
• advanced-plugin-pattern - Structure plugins with proper install function

Decision Trees

When to use ref vs reactive

What type of data?
│
├── Primitives (string, number, boolean)
│   └── ref() ✓
│
├── Objects/Arrays (need deep reactivity)
│   └── reactive() ✓
│
├── Large objects (performance critical)
│   └── shallowRef() or shallowReactive() ✓
│
└── Non-reactive data (class instances, external libs)
    └── markRaw() ✓

When to use useFetch vs $fetch (Nuxt)

Where is the code running?
│
├── Component/Page (need SSR + reactivity)
│   └── useFetch() or useAsyncData() ✓
│
├── Server API route
│   └── $fetch() ✓
│
├── Event handler (client-side only)
│   └── $fetch() ✓
│
└── Composable (reusable)
    └── useFetch() with key ✓

Component communication pattern

What's the relationship?
│
├── Parent → Child
│   └── Props ✓
│
├── Child → Parent
│   └── Emits ✓
│
├── Siblings
│   └── Pinia store or provide/inject ✓
│
├── Deep nesting (prop drilling)
│   └── provide/inject ✓
│
└── Global state
    └── Pinia store ✓

Anti-Patterns to Avoid

❌ DON'T:

• Use Options API in new Vue 3 projects
• Mutate props directly
• Use this in <script setup>
• Create reactive() with primitives
• Use v-if and v-for on same element
• Forget :key in v-for loops
• Use index as :key for dynamic lists
• Access refs without .value in script
• Nest Pinia stores unnecessarily
• Use $fetch in components (use useFetch)

✅ DO:

• Use Composition API with <script setup>
• Define props and emits with TypeScript
• Use computed for derived state
• Use watchEffect for side effects
• Leverage VueUse composables
• Use Pinia for global state
• Handle loading/error states
• Clean up effects in onUnmounted
• Use Suspense for async components

Performance Checklist

Before shipping:

• Bundle analyzed? No unexpected large dependencies
• Lazy loading? Routes and heavy components code-split
• Reactivity optimized? Using shallowRef where appropriate
• SSR working? No hydration mismatches
• Images optimized? Using nuxt/image or similar
• API calls deduplicated? Using useFetch with proper keys
• State management efficient? Not over-fetching in stores
• List rendering optimized? Virtual scroll for long lists

Full Compiled Document

For detailed code examples, implementation patterns, and comprehensive explanations: AGENTS.md

Each section in AGENTS.md contains:

• Detailed explanations of why patterns matter
• Incorrect vs Correct code comparisons
• Copy-paste ready implementations
• Vue 3 and Nuxt 3 specific examples
• VueUse integration examples