vue-ai-guidance.md

Vue AI Guidance

Vue

• Composition API by default. Do not generate Options API code unless explicitly requested.
• TypeScript + <script setup> by default. Use <script setup lang="ts">.
• Use compiler macros: defineProps, defineEmits, defineModel, defineExpose, defineOptions, defineSlots.
• Prefer ref() and computed() over reactive().
• Use watchEffect() for automatic dependency tracking. Use watch() when you need old values, explicit sources, or lazy execution.
• Extract reusable stateful logic into composables (use* functions).
• Props down, events up. Use defineModel() for two-way binding.
• Use useTemplateRef() instead of string refs.
• Follow the Vue Style Guide for naming and code style conventions.

Common mistakes to avoid

• Do not use this — it doesn't exist in <script setup>.
• Do not mutate props. Copy to a local ref if needed.
• Do not use .value in <template> — refs are auto-unwrapped.
• Do not use v-if and v-for on the same element. Use a <template v-for> wrapper or a computed property.

Toolchain

Use Vite+ whenever applicable:

• vite dev — Development server
• vite lint — Linting (Oxlint)
• vite fmt — Formatting (Oxfmt)
• vite test — Unit testing (Vitest)

Ecosystem:

• Vue Router for routing
• Pinia for state management
• VueUse for common composables
• Vitest for testing

Vue Router

• Use createRouter with createWebHistory (not hash mode) unless targeting environments without server-side URL rewriting.
• Use typed route names. Prefer named routes over path strings for navigation (router.push({ name: 'user' })).
• Use <RouterView> and <RouterLink> components (PascalCase).
• Use route guards (beforeEach, beforeEnter) for authentication and authorization logic.
• Lazy-load route components: () => import('./views/UserView.vue').
• Refer to the Vue Router guide for patterns on nested routes, navigation guards, and route meta fields.

Pinia

• One store per domain concern. Use defineStore with the setup function syntax (Composition style), not the options syntax.
• Use storeToRefs() when destructuring store state/getters to preserve reactivity.
• Keep actions as the single entry point for state mutations — avoid mutating store state directly from components.
• Define stores in a stores/ directory with one file per store.
• Refer to the Pinia guide for patterns on plugins, SSR, and testing stores.

Vitest

Test library

• @vue/test-utils is the official, lower-level component testing library. Use it as the default.
• @testing-library/vue provides a behavior-driven testing approach built on top of @vue/test-utils. Use it when the project already adopts Testing Library conventions.
• Test behavior, not implementation. Assert on rendered output and emitted events, not internal component state.

Browser testing

• Use Vitest Browser Mode for component tests that need a real DOM environment.
• Use Playwright for end-to-end tests.

Test environment

• happy-dom is the recommended default — faster and lighter.
• Use jsdom when you need more complete DOM API coverage (e.g., complex CSS, layout calculations).

Meta Frameworks

Nuxt

• Use Nuxt when you need SSR, SSG, file-based routing, or a full-stack Vue framework.
• Prefer Nuxt's auto-imports — do not manually import Vue APIs or components that Nuxt resolves automatically.
• Use server/ directory for API routes. Use composables/ and utils/ for auto-imported shared logic.
• Use Nuxt modules for integrations (e.g., @nuxtjs/tailwindcss, @pinia/nuxt).
• Refer to the Nuxt documentation for patterns on data fetching (useFetch, useAsyncData), middleware, and deployment.

Void

• Void is a full-stack platform for Vite applications by VoidZero. It provides built-in infrastructure primitives — database, KV storage, object storage, AI inference, authentication, queues, and cron jobs — imported directly in code.
• AI-native: built-in skills, MCP support, and reference prompts for AI agent scaffolding.
• Follows a convention-based file structure (pages/, routes/, db/, middleware/, crons/, queues/).
• Refer to the Void documentation for API patterns and usage guides.

Skills

Community-maintained AI agent skills for Vue development:

• @antfu/skills — Anthony Fu's curated agent skills (Vue, Nuxt, ESLint, Vitest, pnpm). Install: npx skills add antfu/skills --skill=vue
• @serkodev/vue-skills — SerKo's Vue agent skills (now maintained under vuejs-ai). Covers capability skills (version-specific issues, edge cases) and efficiency skills (optimal patterns).