Vue.js Best Practices

Comprehensive best practices guide for Vue.js 3 applications. Contains guidelines across multiple categories to ensure idiomatic, maintainable, and scalable Vue.js code, including Tailwind CSS integration patterns for utility-first styling and PrimeVue component library best practices.

When to Apply

Reference these guidelines when:

• Writing new Vue components or composables
• Implementing features with Composition API
• Reviewing code for Vue.js patterns compliance
• Refactoring existing Vue.js code
• Setting up component architecture
• Working with Nuxt.js applications
• Styling Vue components with Tailwind CSS utility classes
• Creating design systems with Tailwind and Vue
• Using PrimeVue component library natively
• Customizing PrimeVue theme through design tokens and definePreset()

Rule Categories

Quick Reference

1. Composition API Best Practices

• composition-script-setup - Always use <script setup> for single-file components
• composition-ref-vs-reactive - Use ref() for primitives, reactive() for objects
• composition-computed-derived - Use computed() for all derived state
• composition-watch-side-effects - Use watch()/watchEffect() only for side effects
• composition-composables - Extract reusable logic into composables
• composition-lifecycle-order - Place lifecycle hooks after reactive state declarations
• composition-avoid-this - Never use this in Composition API

2. Component Design

• component-single-responsibility - One component, one purpose
• component-naming-convention - Use PascalCase for components, kebab-case in templates
• component-small-focused - Keep components under 200 lines
• component-presentational-container - Separate logic from presentation when beneficial
• component-slots-flexibility - Use slots for flexible component composition
• component-expose-minimal - Only expose what's necessary via defineExpose()

3. Reactivity Patterns

• reactive-const-refs - Always declare refs with const
• reactive-unwrap-template - Let Vue unwrap refs in templates (no .value)
• reactive-shallow-large-data - Use shallowRef()/shallowReactive() for large non-reactive data
• reactive-readonly-props - Use readonly() to prevent mutations
• reactive-toRefs-destructure - Use toRefs() when destructuring reactive objects
• reactive-avoid-mutation - Prefer immutable updates for complex state

4. Props & Events

• props-define-types - Always define prop types with defineProps<T>()
• props-required-explicit - Be explicit about required vs optional props
• props-default-values - Provide sensible defaults with withDefaults()
• props-immutable - Never mutate props directly
• props-validation - Use validator functions for complex prop validation
• events-define-emits - Always define emits with defineEmits<T>()
• events-naming - Use kebab-case for event names in templates
• events-payload-objects - Pass objects for events with multiple values

5. Template Patterns

• template-v-if-v-show - Use v-if for conditional rendering, v-show for toggling
• template-v-for-key - Always use unique, stable :key with v-for
• template-v-if-v-for - Never use v-if and v-for on the same element
• template-computed-expressions - Move complex expressions to computed properties
• template-event-modifiers - Use event modifiers (.prevent, .stop) appropriately
• template-v-bind-shorthand - Use shorthand syntax (: for v-bind, @ for v-on)
• template-v-model-modifiers - Use v-model modifiers (.trim, .number, .lazy)

6. Code Organization

• organization-feature-folders - Organize by feature, not by type
• organization-composables-folder - Keep composables in dedicated composables/ folder
• organization-barrel-exports - Use index files for clean imports
• organization-consistent-naming - Follow consistent naming conventions
• organization-colocation - Colocate related files (component, tests, styles)

7. TypeScript Integration

• typescript-generic-components - Use generics for reusable typed components
• typescript-prop-types - Use TypeScript interfaces for prop definitions
• typescript-emit-types - Type emit payloads explicitly
• typescript-ref-typing - Specify types for refs when not inferred
• typescript-template-refs - Type template refs with ref<InstanceType<typeof Component> | null>(null)

8. Error Handling

• error-boundaries - Use onErrorCaptured() for component error boundaries
• error-async-handling - Handle errors in async operations explicitly
• error-provide-fallbacks - Provide fallback UI for error states
• error-logging - Log errors appropriately for debugging

9. Tailwind CSS

• tailwind-utility-first - Apply utility classes directly in templates, avoid custom CSS
• tailwind-class-order - Use consistent class ordering (layout → spacing → typography → visual)
• tailwind-responsive-mobile-first - Use mobile-first responsive design (sm:, md:, lg:)
• tailwind-component-extraction - Extract repeated utility patterns into Vue components
• tailwind-dynamic-classes - Use computed properties or helper functions for dynamic classes
• tailwind-complete-class-strings - Always use complete class strings, never concatenate
• tailwind-state-variants - Use state variants (hover:, focus:, active:) for interactions
• tailwind-dark-mode - Use dark: prefix for dark mode support
• tailwind-design-tokens - Configure design tokens in Tailwind config for consistency
• tailwind-avoid-apply-overuse - Limit @apply usage; prefer Vue components for abstraction

10. PrimeVue

• primevue-use-natively - Use PrimeVue components as-is with their documented props and API
• primevue-design-tokens - Customize appearance exclusively through design tokens and definePreset()
• primevue-no-pt-overrides - NEVER use PassThrough (pt) API to restyle components
• primevue-no-unstyled-mode - NEVER use unstyled mode to strip and rebuild component styles
• primevue-no-wrapper-components - NEVER wrap PrimeVue components just to override their styling
• primevue-props-api - Use built-in props (severity, size, outlined, rounded, raised, text) for variants
• primevue-css-layers - Configure CSS layer ordering for clean Tailwind coexistence
• primevue-typed-components - Leverage PrimeVue's TypeScript support for type safety
• primevue-accessibility - Maintain WCAG compliance with proper aria attributes
• primevue-lazy-loading - Use async components for large PrimeVue imports

Key Principles

Composition API Best Practices

The Composition API is the recommended approach for Vue.js 3. Follow these patterns:

• Always use <script setup>: More concise, better TypeScript inference, and improved performance
• Organize code by logical concern: Group related state, computed properties, and functions together
• Extract reusable logic to composables: Follow the use prefix convention (e.g., useAuth, useFetch)
• Keep setup code readable: Order: props/emits, reactive state, computed, watchers, methods, lifecycle hooks

Component Design Principles

Well-designed components are the foundation of maintainable Vue applications:

• Single Responsibility: Each component should do one thing well
• Props Down, Events Up: Follow unidirectional data flow
• Prefer Composition over Inheritance: Use composables and slots for code reuse
• Keep Components Small: If a component exceeds 200 lines, consider splitting it

Reactivity Guidelines

Understanding Vue's reactivity system is crucial:

• ref vs reactive: Use ref() for primitives and values you'll reassign; use reactive() for objects you'll mutate
• Computed for derived state: Never store derived state in refs; use computed() instead
• Watch for side effects: Only use watch() for side effects like API calls or localStorage
• Be mindful of reactivity loss: Don't destructure reactive objects without toRefs()

Props & Events Patterns

Proper component communication ensures maintainable code:

• Type your props: Use TypeScript interfaces with defineProps<T>()
• Validate complex props: Use validator functions for business logic validation
• Emit typed events: Use defineEmits<T>() for type-safe event handling
• Use v-model for two-way binding: Implement modelValue prop and update:modelValue emit

Common Patterns

Script Setup Structure

Recommended structure for <script setup>:

<script setup lang="ts">
// 1. Imports
import { ref, computed, watch, onMounted } from 'vue'
import { useRouter } from 'vue-router'
import type { User } from '@/types'

// 2. Props and Emits
const props = defineProps<{
  userId: string
  initialData?: User
}>()

const emit = defineEmits<{
  submit: [user: User]
  cancel: []
}>()

// 3. Composables
const router = useRouter()
const { user, loading, error } = useUser(props.userId)

// 4. Reactive State
const formData = ref({ name: '', email: '' })
const isEditing = ref(false)

// 5. Computed Properties
const isValid = computed(() => {
  return formData.value.name.length > 0 && formData.value.email.includes('@')
})

// 6. Watchers (for side effects only)
watch(() => props.userId, (newId) => {
  fetchUserData(newId)
})

// 7. Methods
function handleSubmit() {
  if (isValid.value) {
    emit('submit', formData.value)
  }
}

// 8. Lifecycle Hooks
onMounted(() => {
  if (props.initialData) {
    formData.value = { ...props.initialData }
  }
})
</script>

Composable Pattern

Correct: Well-structured composable

// composables/useUser.ts
import { ref, computed, watch } from 'vue'
import type { Ref } from 'vue'
import type { User } from '@/types'

export function useUser(userId: Ref<string> | string) {
  // State
  const user = ref<User | null>(null)
  const loading = ref(false)
  const error = ref<Error | null>(null)

  // Computed
  const fullName = computed(() => {
    if (!user.value) return ''
    return `${user.value.firstName} ${user.value.lastName}`
  })

  // Methods
  async function fetchUser(id: string) {
    loading.value = true
    error.value = null
    try {
      const response = await api.getUser(id)
      user.value = response.data
    } catch (e) {
      error.value = e as Error
    } finally {
      loading.value = false
    }
  }

  // Auto-fetch when userId changes (if reactive)
  if (isRef(userId)) {
    watch(userId, (newId) => fetchUser(newId), { immediate: true })
  } else {
    fetchUser(userId)
  }

  // Return
  return {