1# Vue Common Gotchas & Edge Cases
2 
3Critical Vue 3 gotchas that cause silent failures or hard-to-debug issues.
4 
5> Based on [vuejs-ai/skills](https://github.com/vuejs-ai/skills) vue-best-practices. For comprehensive coverage (200+ rules), see the upstream repo.
6 
7## Reactivity
8 
9### Always Use `.value` When Accessing ref() in Scripts
10 
11**Impact: HIGH** - Forgetting `.value` causes silent failures.
12 
13```ts
14const count = ref(0)
15 
16// WRONG
17count++           // Tries to increment the ref object
18count = 5         // Reassigns variable, loses reactivity
19items.push(4)     // Error: push is not a function
20 
21// CORRECT
22count.value++
23count.value = 5
24items.value.push(4)
25 
26// In templates - NO .value needed (Vue unwraps automatically)
27// {{ count }} works, not {{ count.value }}
28```
29 
30### Never Destructure reactive() Objects Directly
31 
32**Impact: HIGH** - Destructuring breaks reactive connection.
33 
34```ts
35const state = reactive({ count: 0, name: 'Vue' })
36 
37// WRONG - destructured variables lose reactivity
38const { count, name } = state
39state.count++
40console.log(count)  // Still 0!
41 
42// CORRECT - use toRefs()
43const { count, name } = toRefs(state)
44state.count++
45console.log(count.value)  // 1
46 
47// BEST - just use ref() instead of reactive()
48const count = ref(0)
49const name = ref('Vue')
50```
51 
52### Proxy Identity Hazard with reactive()
53 
54```ts
55const raw = {}
56const proxy = reactive(raw)
57 
58// WRONG - comparing different objects
59console.log(proxy === raw) // false
60 
61// WRONG - creating multiple proxies
62const a = reactive({})
63const b = reactive(a)  // Returns same proxy
64console.log(a === b) // true (same object)
65 
66// GOTCHA - nested objects get proxied too
67const nested = reactive({ obj: {} })
68console.log(nested.obj === nested.obj) // true (same proxy)
69```
70 
71## Computed Properties
72 
73### No Side Effects in Computed Getters
74 
75**Impact: HIGH** - Side effects break reactivity model.
76 
77```ts
78// WRONG - mutates state
79const doubled = computed(() => {
80  count.value++  // Side effect!
81  return count.value * 2
82})
83 
84// WRONG - async operation
85const data = computed(async () => {
86  return await fetch('/api')  // Side effect!
87})
88 
89// CORRECT - pure computation only
90const doubled = computed(() => count.value * 2)
91 
92// For side effects, use watch:
93watch(count, (newVal) => {
94  document.title = `Count: ${newVal}`
95})
96```
97 
98### Computed Returns Are Read-Only
99 
100```ts
101const fullName = computed(() => `${first.value} ${last.value}`)
102 
103// WRONG - computed values are read-only
104fullName.value = 'John Doe'  // Error!
105 
106// CORRECT - use writable computed
107const fullName = computed({
108  get: () => `${first.value} ${last.value}`,
109  set: (val) => {
110    const [f, l] = val.split(' ')
111    first.value = f
112    last.value = l
113  }
114})
115```
116 
117## Watchers
118 
119### Clean Up Async Operations to Prevent Race Conditions
120 
121**Impact: HIGH** - Stale requests can overwrite newer data.
122 
123```ts
124const query = ref('')
125const results = ref([])
126 
127// WRONG - race condition
128watch(query, async (q) => {
129  const res = await fetch(`/api?q=${q}`)
130  results.value = await res.json()  // May overwrite newer results!
131})
132 
133// CORRECT - use onWatcherCleanup (Vue 3.5+)
134watch(query, async (q) => {
135  const controller = new AbortController()
136  onWatcherCleanup(() => controller.abort())
137 
138  try {
139    const res = await fetch(`/api?q=${q}`, { signal: controller.signal })
140    results.value = await res.json()
141  } catch (e) {
142    if (e.name !== 'AbortError') throw e
143  }
144})
145 
146// Or use onCleanup parameter
147watch(query, async (q, oldQ, onCleanup) => {
148  const controller = new AbortController()
149  onCleanup(() => controller.abort())
150  // ... same as above
151})
152```
153 
154### Deep Watch Returns Same Object Reference
155 
156```ts
157const obj = reactive({ nested: { count: 0 } })
158 
159// GOTCHA - oldValue === newValue for deep watches
160watch(obj, (newVal, oldVal) => {
161  console.log(newVal === oldVal)  // true! Same object
162}, { deep: true })
163 
164// If you need old value, clone first:
165watch(
166  () => structuredClone(obj),
167  (newVal, oldVal) => { /* now different */ }
168)
169```
170 
171## Props
172 
173### Props Are Read-Only - Never Mutate
174 
175**Impact: HIGH** - Breaks one-way data flow.
176 
177```ts
178const props = defineProps<{ count: number; user: User }>()
179 
180// WRONG - direct mutation
181props.count++  // Vue warning
182props.user.name = 'New'  // No warning but still wrong!
183 
184// CORRECT - emit to parent
185const emit = defineEmits(['update:count', 'update-user'])
186emit('update:count', props.count + 1)
187emit('update-user', { ...props.user, name: 'New' })
188 
189// Or create local copy
190const localUser = ref({ ...props.user })
191```
192 
193### Destructured Props Don't Update Watchers (pre-3.5)
194 
195```ts
196// WRONG (Vue < 3.5)
197const { count } = defineProps<{ count: number }>()
198watch(count, () => {})  // Won't trigger!
199 
200// CORRECT - use getter
201const props = defineProps<{ count: number }>()
202watch(() => props.count, () => {})
203 
204// Vue 3.5+ - destructuring works with reactive props
205const { count } = defineProps<{ count: number }>()
206watch(() => count, () => {})  // Works in 3.5+
207```
208 
209## Lifecycle Hooks
210 
211### Register Hooks Synchronously During Setup
212 
213**Impact: HIGH** - Async hooks silently fail.
214 
215```ts
216// WRONG - hook registered after await
217async setup() {
218  const data = await fetchData()
219  onMounted(() => {})  // Will NEVER run!
220}
221 
222// WRONG - hook in setTimeout
223setup() {
224  setTimeout(() => {
225    onMounted(() => {})  // Will NEVER run!
226  }, 100)
227}
228 
229// CORRECT - register synchronously, async inside
230setup() {
231  onMounted(async () => {
232    const data = await fetchData()
233  })
234}
235```
236 
237## Templates
238 
239### Never Use v-if with v-for on Same Element
240 
241**Impact: HIGH** - Vue 2/3 precedence differs.
242 
243```vue
244<!-- WRONG - ambiguous precedence -->
245<li v-for="user in users" v-if="user.active" :key="user.id">
246 
247<!-- Vue 3: v-if runs FIRST, 'user' undefined! -->
248 
249<!-- CORRECT - computed filter -->
250<li v-for="user in activeUsers" :key="user.id">
251 
252<script setup>
253const activeUsers = computed(() => users.filter(u => u.active))
254</script>
255 
256<!-- CORRECT - template wrapper -->
257<template v-for="user in users" :key="user.id">
258  <li v-if="user.active">{{ user.name }}</li>
259</template>
260```
261 
262### Template Refs Are Null with v-if
263 
264```ts
265const inputRef = ref<HTMLInputElement | null>(null)
266 
267// GOTCHA - ref is null when element hidden
268<input v-if="show" ref="inputRef" />
269 
270// WRONG - may be null
271inputRef.value.focus()  // Error if !show
272 
273// CORRECT - null check
274inputRef.value?.focus()
275 
276// Or use watchEffect with flush: 'post'
277watchEffect(() => {
278  inputRef.value?.focus()
279}, { flush: 'post' })
280```
281 
282## defineModel
283 
284### Object Mutations Don't Emit
285 
286```ts
287const model = defineModel<{ name: string }>()
288 
289// WRONG - mutation doesn't notify parent
290model.value.name = 'New'  // Parent won't know!
291 
292// CORRECT - replace entire object
293model.value = { ...model.value, name: 'New' }
294```
295 
296### Updated Value Needs nextTick
297 
298```ts
299const model = defineModel<string>()
300 
301// WRONG - value not updated yet
302model.value = 'new'
303console.log(model.value)  // Still old value!
304 
305// CORRECT - wait for nextTick
306model.value = 'new'
307await nextTick()
308console.log(model.value)  // Now 'new'
309```
310 
311## Component Events
312 
313### Undeclared Emits Can Fire Twice
314 
315```ts
316// WRONG - missing emit declaration causes double firing
317const emit = defineEmits([])  // 'click' not declared
318<button @click="emit('click')">  // Fires twice!
319 
320// CORRECT - declare all custom events
321const emit = defineEmits(['click'])
322```
323 
324### Events Don't Bubble Through Components
325 
326```vue
327<!-- Parent can't listen to grandchild events directly -->
328<Grandparent>
329  <Parent>
330    <Child @custom="handler" />  <!-- Only Parent can listen -->
331  </Parent>
332</Grandparent>
333 
334<!-- Solution: re-emit or use provide/inject -->
335```
336 
337## Provide/Inject
338 
339### Reactivity Not Automatic
340 
341```ts
342// Provider
343const count = ref(0)
344provide('count', count)  // Pass the ref, not .value
345 
346// Consumer
347const count = inject('count')  // Receives the ref
348console.log(count.value)  // Reactive!
349 
350// WRONG - loses reactivity
351provide('count', count.value)  // Just passes number
352```
353 
354### Must Call Provide Synchronously
355 
356```ts
357// WRONG - provide after async
358async setup() {
359  await fetchData()
360  provide('key', value)  // Silently fails!
361}
362 
363// CORRECT
364setup() {
365  provide('key', value)  // Synchronous
366  onMounted(async () => {
367    await fetchData()
368  })
369}
370```
371 
372## SSR
373 
374### Lifecycle Hooks Don't Run on Server
375 
376```ts
377// onMounted, onUpdated, onUnmounted - client only
378onMounted(() => {
379  // Only runs in browser
380  window.addEventListener('resize', handler)
381})
382 
383// For SSR, use onServerPrefetch for data
384onServerPrefetch(async () => {
385  data.value = await fetchData()
386})
387```
388 
389### Hydration Mismatch Causes
390 
391Common causes:
392 
393- Browser-only APIs (`window`, `localStorage`)
394- Different timestamps
395- Random values
396- User-agent specific rendering
397 
398```ts
399// WRONG
400const width = ref(window.innerWidth)  // undefined on server
401 
402// CORRECT
403const width = ref(0)
404onMounted(() => {
405  width.value = window.innerWidth
406})
407```
408 
409## Performance
410 
411### Use shallowRef for Large Non-Reactive Data
412 
413```ts
414// WRONG - deep reactivity overhead
415const hugeList = ref(thousandsOfItems)
416 
417// CORRECT - only track .value assignment
418const hugeList = shallowRef(thousandsOfItems)
419 
420// Trigger update by replacing entire array
421hugeList.value = [...hugeList.value, newItem]
422```
423 
424### markRaw for Non-Reactive Objects
425 
426```ts
427// WRONG - Chart.js instance becomes reactive (breaks it)
428const chart = ref(new Chart(ctx, config))
429 
430// CORRECT - mark as non-reactive
431const chart = ref(markRaw(new Chart(ctx, config)))
432```
433 
434## References
435 
436- [vuejs-ai/skills vue-best-practices](https://github.com/vuejs-ai/skills/tree/main/skills/vue-best-practices) - Full 200+ rules
437- [Vue Style Guide](https://vuejs.org/style-guide/)
438- [Vue 3 Migration Guide](https://v3-migration.vuejs.org/)
439