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 {
how to use vue-best-practices
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use vue-best-practices on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add vue-best-practices
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/dedalus-erp-pas/foundation-skills --skill vue-best-practicescopy
The skills CLI fetches vue-best-practices from GitHub repository dedalus-erp-pas/foundation-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/vue-best-practices
Reload or restart Cursor to activate vue-best-practices. Access the skill through slash commands (e.g., /vue-best-practices) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?