Comprehensive Vue 3 reference covering Composition API, Pinia, Vue Router, Nuxt 4, and testing — production patterns with TypeScript throughout.
\n\n\nVue 3 / Nuxt 4 ecosystem facts verified as of 2026-07-05.
\n
What data do I need to make reactive?\n│\n├─ A single primitive (string, number, boolean)?\n│ └─ ref()\n│ const count = ref(0)\n│ const name = ref('')\n│\n├─ A plain object or array with deep reactivity?\n│ ├─ Will I destructure it or pass properties individually?\n│ │ └─ reactive() — but use toRefs() when destructuring\n│ └─ Will I replace the whole object at once?\n│ └─ ref() — ref.value = newObject\n│\n├─ Derived/computed state from other reactive sources?\n│ └─ computed()\n│ const doubled = computed(() => count.value * 2)\n│\n├─ A large object where only top-level keys change?\n│ └─ shallowRef() or shallowReactive()\n│ const state = shallowRef({ nested: { big: 'data' } })\n│\n├─ Side effects that should run when dependencies change?\n│ ├─ Don't need to know old value, auto-tracks dependencies?\n│ │ └─ watchEffect(() => { ... })\n│ └─ Need old/new values, explicit sources, or lazy execution?\n│ └─ watch(source, (newVal, oldVal) => { ... })\n│\n└─ Data that should NOT be reactive (raw DOM, third-party instances)?\n └─ markRaw(obj) or shallowRef(obj)\nHow far does data need to travel?\n│\n├─ Parent → direct child?\n│ └─ props (defineProps)\n│ Direct, explicit, type-safe\n│\n├─ Child → parent (user action / data update)?\n│ └─ emit (defineEmits)\n│ defineEmits<{ change: [value: string] }>()\n│\n├─ Parent ↔ child bidirectional binding?\n│ └─ v-model via defineModel() (Vue 3.4+)\n│ const model = defineModel<string>()\n│\n├─ Ancestor → deep descendant (prop drilling problem)?\n│ └─ provide / inject\n│ Use InjectionKey<T> for type safety\n│\n├─ Siblings or unrelated components?\n│ ├─ Simple/few shared values?\n│ │ └─ provide / inject from a common ancestor\n│ └─ Complex shared state or cross-tree communication?\n│ └─ Pinia store\n│\n├─ Truly global state (user session, cart, preferences)?\n│ └─ Pinia store\n│ defineStore with setup syntax\n│\n└─ One-time events between distant components (rare)?\n └─ Pinia action + watch, or mitt event bus\n Avoid: Vue removed $emit on root in Vue 3\n<script setup> — the standard<script setup lang=\"ts\">\nimport { ref, computed, watch, onMounted } from 'vue'\n\n// Props — with TypeScript generics (no runtime declaration needed)\nconst props = defineProps<{\n title: string\n count?: number\n}>()\n\n// Props with defaults\nconst props = withDefaults(defineProps<{\n size: 'sm' | 'md' | 'lg'\n disabled?: boolean\n}>(), {\n size: 'md',\n disabled: false,\n})\n\n// Emits — type-safe event signatures\nconst emit = defineEmits<{\n change: [value: string] // named tuple syntax (Vue 3.3+)\n update: [id: number, data: object]\n close: []\n}>()\n\n// Reactive state\nconst count = ref(0)\nconst user = reactive({ name: '', email: '' })\n\n// Computed\nconst doubled = computed(() => count.value * 2)\n\n// Watch\nwatch(count, (newVal, oldVal) => {\n console.log(`count changed from ${oldVal} to ${newVal}`)\n})\n\n// Lifecycle\nonMounted(() => {\n console.log('component mounted')\n})\n</script>\ndefineModel — v-model binding (Vue 3.4+)<!-- Child component: MyInput.vue -->\n<script setup lang=\"ts\">\nconst model = defineModel<string>({ required: true })\n\n// Named v-model: <MyInput v-model:title=\"...\" />\nconst title = defineModel<string>('title')\n\n// With modifiers\nconst [modelValue, modifiers] = defineModel<string, 'trim' | 'uppercase'>()\n</script>\n\n<template>\n <input :value=\"model\" @input=\"model = $event.target.value\" />\n</template>\ndefineExpose — expose to parent refs<script setup lang=\"ts\">\nconst inputRef = ref<HTMLInputElement | null>(null)\n\nfunction focus() {\n inputRef.value?.focus()\n}\n\n// Expose public API for parent template refs\ndefineExpose({ focus })\n</script>\ndefineOptions — component meta (Vue 3.3+)<script setup lang=\"ts\">\ndefineOptions({\n name: 'MyComponent',\n inheritAttrs: false,\n})\n</script>\ndefineSlots — type slots (Vue 3.3+)<script setup lang=\"ts\">\ndefineSlots<{\n default(props: { item: User }): any\n header(props: {}): any\n}>()\n</script>\n// stores/counter.ts\nimport { defineStore } from 'pinia'\nimport { ref, computed } from 'vue'\n\nexport const useCounterStore = defineStore('counter', () => {\n // state\n const count = ref(0)\n const name = ref('Counter')\n\n // getters\n const doubled = computed(() => count.value * 2)\n\n // actions\n function increment() {\n count.value++\n }\n\n async function fetchData() {\n const data = await api.get('/data')\n count.value = data.total\n }\n\n return { count, name, doubled, increment, fetchData }\n})\nexport const useCounterStore = defineStore('counter', {\n state: () => ({ count: 0 }),\n getters: {\n doubled: (state) => state.count * 2,\n },\n actions: {\n increment() { this.count++ },\n },\n})\n<script setup lang=\"ts\">\nimport { storeToRefs } from 'pinia'\nimport { useCounterStore } from '@/stores/counter'\n\nconst store = useCounterStore()\n\n// storeToRefs preserves reactivity when destructuring state/getters\n// Actions can be destructured directly (they're not reactive)\nconst { count, doubled } = storeToRefs(store)\nconst { increment } = store\n</script>\n// main.ts\nimport { createPinia } from 'pinia'\nimport piniaPluginPersistedstate from 'pinia-plugin-persistedstate'\n\nconst pinia = createPinia()\npinia.use(piniaPluginPersistedstate)\n\n// In store:\nexport const useAuthStore = defineStore('auth', () => { ... }, {\n persist: true, // or { storage: sessionStorage, paths: ['token'] }\n})\n// router/index.ts\nimport { createRouter, createWebHistory } from 'vue-router'\n\nconst router = createRouter({\n history: createWebHistory(import.meta.env.BASE_URL),\n routes: [\n {\n path: '/',\n name: 'home',\n component: () => import('@/views/HomeView.vue'), // lazy load\n },\n {\n path: '/users/:id',\n name: 'user',\n component: () => import('@/views/UserView.vue'),\n props: true, // passes :id as prop\n meta: { requiresAuth: true },\n },\n {\n path: '/admin',\n component: () => import('@/layouts/AdminLayout.vue'),\n children: [\n { path: '', component: () => import('@/views/admin/Dashboard.vue') },\n { path: 'users', component: () => import('@/views/admin/Users.vue') },\n ],\n },\n { path: '/:pathMatch(.*)*', name: 'not-found', component: NotFound },\n ],\n scrollBehavior(to, from, savedPosition) {\n if (savedPosition) return savedPosition\n if (to.hash) return { el: to.hash, behavior: 'smooth' }\n return { top: 0 }\n },\n})\n\nexport default router\n// Global guard — auth check\nrouter.beforeEach((to, from) => {\n const auth = useAuthStore()\n if (to.meta.requiresAuth && !auth.isLoggedIn) {\n return { name: 'login', query: { redirect: to.fullPath } }\n }\n})\n\n// Per-route guard\n{\n path: '/admin',\n beforeEnter: (to, from) => {\n if (!isAdmin()) return { name: 'forbidden' }\n },\n}\n<!-- In-component guard -->\n<script setup lang=\"ts\">\nimport { onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router'\n\nonBeforeRouteLeave((to, from) => {\n if (hasUnsavedChanges.value) {\n return confirm('Leave without saving?')\n }\n})\n</script>\n// router/index.ts — augment RouteMeta\ndeclare module 'vue-router' {\n interface RouteMeta {\n requiresAuth?: boolean\n title?: string\n breadcrumb?: string\n }\n}\nNuxt 4's flagship change over Nuxt 3 is the app/ source directory (app code separated\nfrom server/ and root config — see ./references/nuxt.md); the\nrendering strategies below are unchanged.
What rendering strategy does my app need?\n│\n├─ Public content (blogs, marketing, docs)?\n│ ├─ Content rarely changes (< daily)?\n│ │ └─ SSG — prerender: { routes: ['/', '/about'] }\n│ └─ Content updated frequently?\n│ └─ ISR — routeRules: { '/blog/**': { isr: 3600 } }\n│\n├─ Dynamic per-user content (dashboards, apps)?\n│ └─ SSR — ssr: true (Nuxt default)\n│ Best for SEO + authenticated data\n│\n├─ Admin panel / internal tool (no SEO needed)?\n│ └─ SPA — ssr: false in nuxt.config.ts\n│\n├─ Mixed needs (marketing pages + app)?\n│ └─ Hybrid — routeRules per path\n│ routeRules: {\n│ '/': { prerender: true },\n│ '/blog/**': { isr: 3600 },\n│ '/app/**': { ssr: true },\n│ '/admin/**': { ssr: false },\n│ }\n│\n└─ Deploying to...\n ├─ Cloudflare Workers/Pages → preset: 'cloudflare'\n ├─ Vercel → preset: 'vercel' (auto-detected)\n ├─ Netlify → preset: 'netlify' (auto-detected)\n └─ Node.js server → preset: 'node-server'\n| Technique | \nWhen to Use | \n
|---|---|
v-memo=\"[dep1, dep2]\" | \nSkip re-rendering a subtree (usually a v-for row) unless listed deps changed — only for measured hot lists | \n
<KeepAlive> | \nCache component instances across tab/route switches; pair with onActivated/onDeactivated for refresh logic | \n
| Virtual scrolling | \nLists with hundreds+ of rows — vue-virtual-scroller or @tanstack/vue-virtual render only visible items | \n
shallowRef / markRaw | \nLarge objects or third-party instances that don't need deep reactivity (see Reactivity Decision Tree) | \n
<!-- v-memo: row re-renders only when item.id or selection state changes -->\n<div\n v-for=\"item in list\"\n :key=\"item.id\"\n v-memo=\"[item.id, item.id === selectedId]\"\n>\n {{ item.name }} — {{ item.id === selectedId ? 'selected' : '' }}\n</div>\nTip: before writing a composable, check VueUse — 200+ battle-tested composables (useLocalStorage, useIntersectionObserver, useDark, ...) that handle SSR and cleanup edge cases.
| Gotcha | \nWhy | \nFix | \n
|---|---|---|
Reactivity lost after destructuring reactive() | \nDestructuring extracts plain values, not refs | \nUse toRefs(state) when destructuring, or use ref() instead of reactive() | \n
ref.value needed in <script>, not in <template> | \nTemplate auto-unwraps top-level refs | \nAccess as count in template, count.value in script | \n
watch doesn't fire on nested object changes | \nDefault is shallow watch | \nAdd { deep: true } or watch a specific nested path () => obj.nested.prop | \n
| Async setup breaks SSR in Nuxt | \nawait in setup() suspends the component | \nUse useAsyncData or useFetch — never raw await fetch() in Nuxt setup | \n
watchEffect runs immediately and tracks lazily | \nTracks dependencies at runtime, not statically | \nUse watch with explicit sources when you need control over what's tracked | \n
Template refs are null before mount | \nref() is null until component is mounted | \nAccess template refs inside onMounted or use watch with { immediate: false } | \n
| Pinia store state lost when destructuring | \nState properties are not reactive when pulled out directly | \nAlways use storeToRefs(store) for state/getters; destructure actions directly | \n
| Props are readonly — mutating causes warning | \nVue enforces one-way data flow | \nEmit event to parent and let parent update; or use defineModel() for two-way binding | \n
computed setter not called on direct assignment | \nComputed with no setter is read-only by default | \nDefine get and set: computed({ get: () => ..., set: (v) => ... }) | \n
v-model on component uses wrong prop/event name | \nDefault v-model uses modelValue prop and update:modelValue event | \nUse defineModel() (Vue 3.4+) or manually wire modelValue prop + update:modelValue emit | \n
provide value is not reactive | \nProviding a raw value instead of a ref | \nProvide ref() or reactive() so injectors see updates: provide('key', ref(value)) | \n
defineAsyncComponent error not caught | \nAsync component rejects without error boundary | \nAdd errorComponent option or wrap in <Suspense> with error slot | \n
| File | \nWhen to Load | \n
|---|---|
| ./references/composition-api.md | \nComposables, provide/inject, template refs, custom directives, Teleport, Suspense, slots, transitions, v-model deep patterns | \n
| ./references/state-routing.md | \nPinia advanced patterns (plugins, SSR, store composition), Vue Router (guards, meta typing, scroll behavior, transitions) | \n
| ./references/nuxt.md | \nNuxt 4 directory structure, data fetching, server routes, middleware, plugins, modules, SEO, deployment, Nuxt Content | \n
| ./references/testing.md | \nVitest setup, Vue Test Utils, Pinia/Router testing, composable testing, MSW, Playwright, Nuxt test utils | \n
This skill encodes fast-moving facts (the Vue 3 minor-version gates, the Nuxt 4\nmeta-framework, the ecosystem package stack). scripts/check-vue-facts.py\nguards them against silent drift — internal consistency in PR CI, live\nmajor-version drift in the scheduled freshness job:
# Structural (PR CI, no network): every catalogued package + Vue version gate is\n# still named in this skill's prose, and the currency note still carries a year.\npython3 skills/vue-ops/scripts/check-vue-facts.py --offline # exit 0 consistent, 10 drift\n\n# Live (weekly freshness job, never blocks a PR): is any documented major\n# now behind npm's latest dist-tag? (e.g. Nuxt 5 while the prose says Nuxt 4.)\npython3 skills/vue-ops/scripts/check-vue-facts.py --live # exit 10 a major moved ahead, 7 npm unreachable\nThe canonical fact list lives in assets/vue-facts.json; when you add or drop a recommendation or the prose stops naming one, update it to match or --offline fails CI.