Vue 3 Reactivity Gotchas Every Developer Hits

Vue 3's Proxy-based reactivity catches more cases than Vue 2's defineProperty approach, but it still has rules. These three gotchas catch most teams I have seen migrate to Vue 3.

Destructuring breaks reactivity on reactive() objects

If you do const { name } = reactive({ name: 'a' }), the local name variable is not reactive — it is a snapshot. The Proxy lives on the object, not on the variable references.

Use toRefs() to keep reactivity when destructuring: const { name } = toRefs(state). Or use ref() instead of reactive() for primitive state — refs survive destructuring because the .value pointer travels with them.

Replacing arrays vs mutating them

Both work. items.value = [...items.value, newItem] and items.value.push(newItem) both trigger updates. The gotcha is mixing patterns in the same component — readers cannot tell whether items is meant to be replaced or mutated, and bugs hide in the inconsistency.

Pick one: usually "replace for clarity, mutate for performance." Document the choice and stick to it.

Reactivity does not cross network or storage boundaries

When you serialize a reactive object to JSON, post it to an API, and deserialize the response, the new object is plain. Wrapping it in reactive() again gives you a fresh proxy — the old references are unrelated.

This sounds obvious but bites in stores that load from localStorage or cache. The store's reactive object stays the same; the loaded object is a separate copy. Merge into the existing reactive state rather than reassigning the whole thing.