awesome-copilot/instructions/vue.instructions.md

description, applyTo

description	applyTo
Comprehensive Vue 3 development standards and best practices: Composition API, `<script setup>`, the full reactivity system, compiler macros (defineModel/defineSlots/defineOptions), built-in components (Teleport/Suspense/Transition/KeepAlive), provide/inject, composables, Pinia, Vue Router, TypeScript, testing, performance, SSR, and security.	**/*.vue, **/*.ts, **/*.js, **/*.css, **/*.scss

Vue 3 Development Instructions

Authoritative guidance for building production-grade Vue 3 applications. Default to the Composition API with <script setup lang="ts">, the modern reactivity system, and the official ecosystem (Pinia, Vue Router, Vite, Vitest). Prefer the idioms below over legacy Options API and Vue 2 patterns.

Project Context

• Vue 3.4+ (use 3.5+ features such as useTemplateRef, useId, and reactive props destructuring where the project's version allows).
• <script setup lang="ts"> single-file components (SFCs) as the default authoring style.
• TypeScript everywhere: components, composables, stores, and router.
• Pinia for state management; Vue Router for routing; Vite for build/dev.
• Vitest + Vue Test Utils (or Testing Library for Vue) for tests.

Authoring Style & Component Design

• Use <script setup> — it is more concise, faster, and has better type inference than setup() or the Options API.
• One responsibility per component; split large components into smaller focused ones plus composables.
• Order an SFC as <script setup>, then <template>, then <style scoped>.
• Name components in PascalCase; use multi-word names (e.g. UserCard, not Card) to avoid clashing with native elements.
• Co-locate component-specific types, and lift shared types into a types/ module.

Compiler Macros (no imports needed)

• defineProps<T>() — declare typed props from a TypeScript interface/type for full inference.
• withDefaults(defineProps<T>(), { ... }) — provide prop defaults (or use reactive props destructuring with defaults in 3.5+).
• defineEmits<{ change: [id: number]; update: [value: string] }>() — declare typed events.
• defineModel<T>() (3.4+) — the canonical way to implement v-model on a component; supports multiple models, arguments, and modifiers.
• defineExpose({ ... }) — explicitly expose a public imperative API; expose nothing by default.
• defineSlots<{ default(props: { item: T }): any }>() — type named/scoped slots.
• defineOptions({ name, inheritAttrs }) — set component options inside <script setup>.
• Never mutate props directly — emit an event, use defineModel, or derive local state with computed/ref.

Reactivity System

Core primitives

• ref() for primitives and single replaceable references; access via .value in script (auto-unwrapped in templates).
• reactive() for deep-reactive objects/collections; never destructure it directly (breaks reactivity) — use toRefs()/toRef().
• computed() for derived values; keep getters pure and side-effect free. Use writable computed (get/set) for two-way derived state.
• Prefer computed over watch whenever you are deriving a value rather than performing a side effect.

Watchers

• watch(source, cb, options) for explicit dependencies; watchEffect(cb) for auto-tracked dependencies.
• Use watch options deliberately: { immediate: true }, { deep: true }, { once: true } (3.4+), and flush: 'post' when you need the DOM updated first.
• Register cleanup with the onCleanup/onWatcherCleanup callback to cancel stale async work (debounce, fetch, listeners).
• Stop manual watchers via their returned handle when they outlive their natural scope.

Advanced reactivity (use intentionally)

• shallowRef / shallowReactive for large or externally-managed data to skip deep tracking.
• readonly() to hand out immutable views of shared state.
• toRef / toRefs to keep reactivity when destructuring; toRaw/markRaw to opt out for non-reactive objects (e.g. class instances, 3rd-party clients).
• effectScope() to group and dispose related effects together (useful in composables/libraries).
• customRef for debounced/throttled or storage-backed refs.

Composables (reusable logic)

• Extract stateful, reusable logic into useXxx() functions under composables/.
• Accept refs/getters as inputs and return refs/computed; use toValue()/MaybeRefOrGetter to normalize ref-or-plain inputs.
• Set up and tear down inside the composable (onMounted/onUnmounted or tryOnScopeDispose) so callers don't leak.
• Keep composables synchronous in their setup phase; expose async actions as returned functions.
• Reach for VueUse for common needs instead of re-implementing (e.g. useStorage, useEventListener, useDebounceFn).

Lifecycle & Effects

• Use onMounted, onBeforeMount, onUpdated, onBeforeUnmount, onUnmounted, onActivated/onDeactivated (with <KeepAlive>), and onErrorCaptured.
• Always clean up timers, listeners, observers, and subscriptions in onUnmounted.
• Guard browser-only APIs (window, document) for SSR; run them in onMounted.

Template Best Practices

• Always set a stable, unique :key on v-for; never use the array index when items can reorder or mutate.
• Never put v-if and v-for on the same element — filter via a computed instead.
• v-show for frequently toggled elements; v-if for conditional mounting.
• Use v-memo to skip re-rendering of expensive static subtrees, and v-once for content that renders a single time.
• Use the : (v-bind) and @ (v-on) shorthands consistently; group nodes with <template> to avoid wrapper elements.
• Avoid heavy expressions in templates — move them to computed or methods.

Slots

• Use named slots for layout extension and scoped slots (<slot :item="item" /> + #default="{ item }") to expose data to the parent.
• Provide sensible fallback slot content.
• Use the v-slot (#) shorthand and dynamic slot names where appropriate.

Built-in Components

• <Teleport to="body"> for modals, toasts, and tooltips that must escape overflow/stacking contexts.
• <Suspense> with #default/#fallback for async setup and lazy components; pair with error handling.
• <Transition> / <TransitionGroup> for enter/leave and list animations (set :key on grouped items).
• <KeepAlive> (with include/exclude/max) to cache component state across toggles; handle onActivated/onDeactivated.
• <component :is="..."> for dynamic components; defineAsyncComponent(() => import('...')) for code-split/lazy loading with loading/error components.

Provide / Inject (dependency injection)

• Type injections with an InjectionKey<T> (Symbol) for safety: provide(key, value) / inject(key).
• Provide a default or assert presence to avoid undefined.
• Prefer readonly() when providing state that children should not mutate; expose explicit updater functions instead.
• Use injection for cross-cutting concerns; use Pinia for app-wide shared state.

Custom Directives & Plugins

• Author directives as objects with mounted/updated (etc.) hooks; keep them DOM-focused (e.g. v-focus, v-click-outside).
• Encapsulate global setup (router, pinia, i18n, UI libs) as plugins via app.use(...); register global config in main.ts.

State Management with Pinia

• Use Pinia for shared/cross-component state; keep component-only state local with ref/reactive.
• Prefer setup stores: defineStore('user', () => { const user = ref(...); const isLoggedIn = computed(...); function login(){}; return { user, isLoggedIn, login } }).
• One store per domain; keep actions for async/side effects and getters pure & synchronous.
• Destructure with storeToRefs() to preserve reactivity; use $patch for batched mutations, $reset to restore state, and $subscribe/$onAction for cross-cutting concerns.
• Handle SSR hydration correctly and keep stores serializable.

Routing with Vue Router

• Define routes with lazy component: () => import('...') for automatic code splitting.
• Use navigation guards (beforeEach, beforeEnter, beforeRouteLeave) for auth and unsaved-changes checks; always resolve/next() exactly once.
• Use route.meta (typed) for per-route config like requiresAuth.
• Read params/query via useRoute() and navigate via useRouter(); treat route.params as reactive (watch it, don't cache).
• Configure scrollBehavior for predictable scroll restoration; enable typed routes where available.

TypeScript Integration

• Type props/emits/slots through generic compiler macros, not runtime object syntax.
• Type refs explicitly when inference is too narrow: ref<User | null>(null).
• Type template refs with useTemplateRef<HTMLInputElement>('input') (3.5+) or ref<HTMLInputElement | null>(null).
• Build generic components with <script setup lang="ts" generic="T">.
• Type provide/inject with InjectionKey<T>; type Pinia stores via their inferred return types.

Styling

• Default to <style scoped>; use :deep(), :slotted(), and :global() selectors deliberately.
• Use v-bind() in <style> to drive CSS from reactive state; prefer CSS custom properties for theming.
• Consider CSS Modules (<style module>) for class-name isolation in larger teams.

Forms & Validation

• Bind inputs with v-model (and defineModel for custom inputs); use modifiers .lazy, .number, .trim.
• Validate with a schema library (Zod/Yup) plus a form library (VeeValidate or FormKit) for non-trivial forms.
• Client validation is for UX only — always validate and sanitize on the server.

Error Handling

• Use onErrorCaptured for component-tree boundaries and app.config.errorHandler for a global hook.
• Wrap async/lazy boundaries with <Suspense> + an error fallback.
• Surface user-friendly errors; log diagnostics to your monitoring pipeline.

Performance

• Code-split routes and heavy components (defineAsyncComponent, dynamic import()).
• Use computed for caching, v-memo/v-once for static subtrees, and shallowRef/shallowReactive for big datasets.
• Virtualize long lists (e.g. vue-virtual-scroller); paginate or window large data.
• Avoid unnecessary deep reactivity and avoid creating new object/array literals inline in templates.
• In 3.5+, consider lazy hydration strategies for SSR to reduce time-to-interactive.

SSR / Meta-frameworks

• Prefer Nuxt for SSR/SSG/hybrid rendering unless you have a reason to hand-roll SSR.
• Keep code isomorphic: guard browser APIs, avoid module-level shared mutable state across requests, and ensure stores are request-scoped.
• Match server and client output to prevent hydration mismatches.

Accessibility

• Use semantic HTML first; add ARIA only to fill genuine gaps.
• Ensure full keyboard operability and visible focus states.
• Manage focus on route changes and when opening/closing dialogs (trap focus in modals).
• Give icon-only controls accessible names (aria-label); associate labels with inputs.

Security

• Never render untrusted input with v-html; sanitize (e.g. DOMPurify) if it is unavoidable.
• Avoid dynamic :is/:href/:src from untrusted sources; validate URLs (block javascript: schemes).
• Keep secrets server-side; only expose VITE_-prefixed env vars intentionally meant to be public.
• Apply a Content Security Policy and standard CSRF/XSS protections at the app layer.

Testing

• Unit-test composables as plain functions; component-test with Vue Test Utils / Testing Library.
• Test observable behavior and rendered output, not internal implementation details.
• Mock stores with createTestingPinia; stub router and async boundaries as needed.
• Cover critical user journeys with end-to-end tests (Playwright or Cypress).

Tooling

• Use Vite with the official Vue plugin; enable vue-tsc for type-checking in CI.
• Use ESLint (eslint-plugin-vue) and Prettier; enable Volar/Vue official extension for the best DX.
• Manage env via import.meta.env with VITE_-prefixed variables.

Anti-Patterns to Avoid

• Mixing Options API and Composition API arbitrarily in the same codebase.
• Mutating props directly, or destructuring reactive()/Pinia stores without toRefs/storeToRefs.
• Using watch for values that should be computed.
• v-if together with v-for on one element; using array index as :key.
• Heavy logic inside templates; unbounded deep reactivity on large data.
• Leaking timers/listeners by skipping onUnmounted cleanup.
• Rendering untrusted HTML via v-html.