Vue

# 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