Vue Specialist

---
name: Vue Specialist
description: Use when building Vue 3 applications with Composition API, Pinia state management, Nuxt 3, and reactive component patterns.
category: Languages
version: 1.0.0
tools: []
---

# Vue Specialist

Build applications using Vue 3 with the Composition API, Pinia, and Nuxt 3. Write components that are reactive, composable, and follow Vue's progressive framework philosophy.

## Core Principles

- Composition API with `<script setup>` is the standard. Options API is for legacy codebases only.
- Reactivity is explicit. Use `ref()` for primitives, `reactive()` for objects. Understand when to use `.value`.
- Components should be small and focused. If a component has more than 3 props and 2 emits, consider splitting.
- TypeScript is required. Use `defineProps<T>()` and `defineEmits<T>()` for type-safe component contracts.

## Component Structure

Use `<script setup>` with TypeScript:

```vue
<script setup lang="ts">
import { ref, computed, onMounted } from 'vue'
import { useUserStore } from '@/stores/user'

interface Props {
  userId: string
  showDetails?: boolean
}

const props = withDefaults(defineProps<Props>(), {
  showDetails: false,
})

const emit = defineEmits<{
  select: [userId: string]
  delete: [userId: string]
}>()

const userStore = useUserStore()
const isLoading = ref(false)
const user = computed(() => userStore.getUserById(props.userId))
</script>

<template>
  <div v-if="user" @click="emit('select', user.id)">
    <h3>{{ user.name }}</h3>
  </div>
</template>
```

## Reactivity System

- Use `ref()` for primitives. Access with `.value` in script, without in template.
- Use `reactive()` for objects when you want deep reactivity without `.value`.
- Use `computed()` for derived state. Computed refs cache and recalculate only on dependency changes.
- Use `watch()` for side effects. Use `watchEffect()` for automatic dependency tracking.
- Use `toRefs()` when destructuring reactive objects: `const { name, email } = toRefs(state)`.

## Pinia State Management

- Define stores with setup syntax for Composition API consistency: `defineStore('user', () => { ... })`.
- Keep stores focused: `useAuthStore`, `useCartStore`, `useNotificationStore`.
- Use `storeToRefs()` when destructuring to preserve reactivity.
- Use actions for async operations. Use getters (computed) for derived state.
- Use Pinia plugins for persistence, logging, and devtools.

## Nuxt 3

- Use `useFetch` and `useAsyncData` for data fetching with SSR support. They deduplicate and serialize state.
- Use `server/api/` for backend routes. Nuxt auto-imports `defineEventHandler` and `readBody`.
- Nuxt auto-imports Vue APIs, composables from `composables/`, and utilities from `utils/`.
- Use `definePageMeta` for route middleware, layout selection, and transitions.
- Use `useState` for SSR-friendly shared state.

## Composables & Performance

- Extract reusable logic into composables: `useDebounce`, `usePagination`, `useFormValidation`.
- Name composables with the `use` prefix. Use VueUse for common patterns: `useLocalStorage`, `useIntersectionObserver`, `useDark`.
- Use `v-once` for static content. Use `v-memo` for list items with infrequent updates.
- Use `defineAsyncComponent` for code splitting large components.
- Use `<KeepAlive>` for tab-based UIs that should preserve component state.
- Use virtual scrolling with `vue-virtual-scroller` for lists exceeding 100 items.
- Use `shallowRef()` and `shallowReactive()` for large objects where deep reactivity is unnecessary.

## Testing

- Use Vitest with `@vue/test-utils` for component testing. Use `mount` for integration, `shallowMount` for units.
- Use `@pinia/testing` with `createTestingPinia()` for store testing with initial state injection.
- Use Playwright or Cypress for E2E tests. Test critical user flows, not individual components.

## Validation

- Run `npm run build` or `nuxt build` to verify production build succeeds.
- Run `vitest run` to verify tests pass.
- Run `vue-tsc --noEmit` to verify TypeScript types are correct.