Skip to content

Vue 3.6 Reactivity Internals: Understanding the Implementation Differences Between ref and reactive

Vue 3's reactivity system is a complete architectural rewrite. From Vue 2's Object.defineProperty to Vue 3's Proxy, it's not just an API change — it's a paradigm shift from "property hijacking" to "object proxying" in the reactivity model. Vue 3.6 further optimizes effect scheduling and memory management on top of this foundation. This article dissects the implementation differences between ref and reactive at the source code level.

The Core Model of the Reactivity System ​

Vue's reactivity system consists of three core parts:

  1. Reactive data: Intercepts read/write operations on data via Proxy
  2. Dependency collection (track): Records the currently executing effect when data is read
  3. Triggering updates (trigger): Notifies all effects dependent on the data to re-execute when data is modified
effect executes → reads reactive data → track collects dependencies → data changes → trigger notifies effect → effect re-executes

The key to this model is: all reactive data read during an effect's execution establishes a relationship with that effect. When any associated data changes, the effect is re-executed.

reactive Implementation ​

The core of reactive is new Proxy(target, handlers), intercepting get, set, has, deleteProperty, and other operations.

typescript
// Vue 3.6 source code simplified
const reactiveMap = new WeakMap<object, any>()

function reactive<T extends object>(target: T): T {
  // Already a reactive object, return directly
  if (target.__v_isReactive) {
    return target
  }

  // Cache check: same object is only proxied once
  const existingProxy = reactiveMap.get(target)
  if (existingProxy) {
    return existingProxy
  }

  const proxy = new Proxy(target, {
    get(target, key, receiver) {
      if (key === '__v_isReactive') return true

      // Special handling for arrays
      const targetIsArray = Array.isArray(target)
      if (targetIsArray && hasOwn(arrayInstrumentations, key)) {
        return Reflect.get(arrayInstrumentations, key, receiver)
      }

      const res = Reflect.get(target, key, receiver)

      // Built-in Symbols skip dependency collection
      if (isSymbol(key) && builtInSymbols.has(key)) {
        return res
      }

      // Dependency collection
      track(target, key)

      // Nested objects are lazily made reactive
      if (isObject(res)) {
        return reactive(res)
      }

      return res
    },

    set(target, key, value, receiver) {
      let oldValue = (target as any)[key]
      const hadKey = Array.isArray(target) && isIntegerKey(key)
        ? Number(key) < target.length
        : hasOwn(target, key)

      const result = Reflect.set(target, key, value, receiver)

      // Avoid duplicate updates triggered by prototype chain sets
      if (target === toRaw(receiver)) {
        if (!hadKey) {
          // New property → ADD
          trigger(target, 'add', key, value)
        } else if (hasChanged(value, oldValue)) {
          // Modified property → SET
          trigger(target, 'set', key, value, oldValue)
        }
      }

      return result
    },

    deleteProperty(target, key) {
      const hadKey = hasOwn(target, key)
      const oldValue = (target as any)[key]
      const result = Reflect.deleteProperty(target, key)
      if (result && hadKey) {
        trigger(target, 'delete', key, undefined, oldValue)
      }
      return result
    },

    has(target, key) {
      const result = Reflect.has(target, key)
      if (!isSymbol(key) || !builtInSymbols.has(key)) {
        track(target, key)
      }
      return result
    },

    ownKeys(target) {
      track(target, Array.isArray(target) ? 'length' : ITERATE_KEY)
      return Reflect.ownKeys(target)
    },
  })

  reactiveMap.set(target, proxy)
  return proxy
}

Several key design decisions are worth noting:

Lazy reactivity: Nested objects are only made reactive when first read, not recursively processed at creation time. This avoids initialization performance overhead and means unaccessed nested objects never create Proxies.

Cache mechanism: reactiveMap ensures that only one Proxy is created per original object. Multiple calls to reactive(obj) return the same proxy.

Array special handling: Vue 3.6 instruments array methods to ensure includes, indexOf, push, pop, and other methods correctly trigger dependency collection and updates.

ref Implementation ​

ref exists to solve a fundamental problem: Proxy cannot proxy primitive values (string, number, boolean). A Proxy's target must be an object; calling new Proxy(42, ...) on a primitive throws a TypeError.

typescript
// Vue 3.6 source code simplified
class RefImpl<T> {
  private _value: T
  private _rawValue: T
  public dep: Dep = new Dep()
  public readonly __v_isRef = true

  constructor(value: T, public readonly __v_isShallow: boolean) {
    this._rawValue = this.__v_isShallow ? value : toRaw(value)
    // Object types are wrapped with reactive
    this._value = this.__v_isShallow ? value : toReactive(value)
  }

  get value() {
    // Dependency collection
    this.dep.track()
    return this._value
  }

  set value(newVal) {
    const useDirectValue = this.__v_isShallow || isShallow(newVal) || isReadonly(newVal)
    const rawNewVal = useDirectValue ? newVal : toRaw(newVal)

    if (hasChanged(rawNewVal, this._rawValue)) {
      this._rawValue = rawNewVal
      this._value = useDirectValue ? newVal : toReactive(newVal)
      // Trigger update
      this.dep.trigger()
    }
  }
}

function ref<T>(value: T): Ref<T> {
  return new RefImpl(value, false)
}

// toReactive: wraps object types with reactive, returns primitives directly
function toReactive(value: T): T {
  return isObject(value) ? reactive(value) : value
}

This is the fundamental reason ref requires .value: a carrier object is needed to intercept read/write operations through getter/setter. .value is the property accessor on this carrier.

Core Differences Between ref and reactive ​

Dimensionreactiveref
Supported data typesObjects onlyObjects + primitives
Proxy mechanismProxy intercepts the entire objectgetter/setter intercepts .value
Nested reactivityAutomatic recursive (lazy)Primitives not recursive, objects delegated to reactive
Dependency storagetarget → key → dep mappingSingle dep on the ref instance
Access methodDirect property access state.countRequires .value
Template auto-unwrappingNot neededAuto-unwrapped (compiler handles)
Replacing entire objectBreaks (Proxy bound to original object)Works (replaces _value)

The last point is a common source of bugs:

typescript
// reactive pitfall
const state = reactive({ count: 0 })
const newState = reactive({ count: 1 })
state = newState // ❌ TypeError: Assignment to constant variable
// Even without const, replacing the reference breaks dependency tracking

// ref doesn't have this problem
const state = ref({ count: 0 })
state.value = { count: 1 } // ✅ Works correctly, old dependencies are cleaned up

The Complete Dependency Collection (track) Flow ​

Vue 3.6 refactored the dependency collection data structure from nested WeakMaps to a flatter structure:

typescript
// Vue 3.6 simplified dependency management

// Currently executing effect
let activeEffect: ReactiveEffect | undefined

// Dependency mapping: target → key → dep
const targetMap = new WeakMap<object, Map<PropertyKey, Dep>>()

function track(target: object, key: PropertyKey) {
  if (!activeEffect) return

  let depsMap = targetMap.get(target)
  if (!depsMap) {
    targetMap.set(target, (depsMap = new Map()))
  }

  let dep = depsMap.get(key)
  if (!dep) {
    depsMap.set(key, (dep = new Dep()))
  }

  dep.track()
}

// Dep class: manages a set of effects
class Dep {
  private effects = new LinkedSet<ReactiveEffect>()

  track() {
    if (activeEffect) {
      this.effects.add(activeEffect)
      // effect also records which deps collected it (for cleanup)
      activeEffect.deps.push(this)
    }
  }

  trigger() {
    // Copy to avoid infinite loops during iteration
    const effects = [...this.effects]
    for (const effect of effects) {
      // Avoid recursive self-calls
      if (effect !== activeEffect) {
        effect.trigger()
      }
    }
  }
}

track is called during effect execution, associating the current activeEffect with the property being read. The key is when activeEffect is set — it's managed by the effect function:

typescript
class ReactiveEffect {
  private fn: () => void
  public scheduler?: (job: () => void) => void
  public deps: Dep[] = []
  private active = true

  constructor(fn: () => void, scheduler?: (job: () => void) => void) {
    this.fn = fn
    this.scheduler = scheduler
  }

  run() {
    // Clean up old dependencies (solves the branch switching problem)
    if (!this.active) {
      return this.fn()
    }

    const prevEffect = activeEffect
    activeEffect = this
    cleanupEffect(this)
    try {
      return this.fn()
    } finally {
      activeEffect = prevEffect
    }
  }

  trigger() {
    if (this.scheduler) {
      // When a scheduler exists, it decides when to execute
      this.scheduler(() => this.run())
    } else {
      this.run()
    }
  }
}

function effect(fn: () => void, options?: { scheduler?: (job: () => void) => void }) {
  const _effect = new ReactiveEffect(fn, options?.scheduler)
  _effect.run()
  return _effect
}

cleanupEffect is a critical step: before each effect re-execution, all old dependency relationships are cleared. This solves the branch switching problem — when a conditional branch changes, dependencies collected in the previous branch should be cleaned up.

typescript
function cleanupEffect(effect: ReactiveEffect) {
  const { deps } = effect
  for (let i = 0; i < deps.length; i++) {
    deps[i].effects.delete(effect)
  }
  deps.length = 0
}

The Complete Trigger Update (trigger) Flow ​

typescript
function trigger(
  target: object,
  type: 'set' | 'add' | 'delete',
  key: PropertyKey,
  newValue?: unknown,
  oldValue?: unknown,
) {
  const depsMap = targetMap.get(target)
  if (!depsMap) return

  const effects: Dep[] = []

  // SET operation: directly trigger the dep for the key
  if (type === 'set') {
    const dep = depsMap.get(key)
    if (dep) effects.push(dep)
  }

  // ADD operation: trigger key's dep + ITERATE_KEY's dep
  if (type === 'add') {
    const dep = depsMap.get(key)
    if (dep) effects.push(dep)

    const iterateDep = depsMap.get(ITERATE_KEY)
    if (iterateDep) effects.push(iterateDep)

    // When adding array elements, length must also trigger
    if (Array.isArray(target)) {
      const lengthDep = depsMap.get('length')
      if (lengthDep) effects.push(lengthDep)
    }
  }

  // DELETE operation: similar to ADD
  if (type === 'delete') {
    const dep = depsMap.get(key)
    if (dep) effects.push(dep)

    const iterateDep = depsMap.get(ITERATE_KEY)
    if (iterateDep) effects.push(iterateDep)
  }

  // Execute all related effects
  for (const dep of effects) {
    dep.trigger()
  }
}

Effect Schedulers and Batching ​

Vue's updates are not synchronous. When multiple reactive states are modified within an event handler, Vue batches all updates and triggers only one component re-render. This mechanism is implemented through schedulers and the microtask queue.

typescript
// Batch queue
const queue = new Set<ReactiveEffect>()
let isFlushing = false
const resolvedPromise = Promise.resolve()

function queueJob(effect: ReactiveEffect) {
  queue.add(effect)
  if (!isFlushing) {
    isFlushing = true
    resolvedPromise.then(flushJobs)
  }
}

function flushJobs() {
  try {
    for (const effect of queue) {
      effect.run()
    }
  } finally {
    queue.clear()
    isFlushing = false
  }
}

// Component effects use schedulers
function setupEffect(instance: ComponentInternalInstance) {
  const update = effect(() => {
    // Render component
    instance.render()
  }, {
    scheduler: (job) => queueJob(job), // Use scheduler instead of immediate execution
  })
}

The effect of batching:

typescript
const state = reactive({ count: 0, name: 'Vue' })

effect(() => {
  console.log(`count: ${state.count}, name: ${state.name}`)
}, {
  scheduler: (job) => queueJob(job),
})

// Batch modifications
state.count = 1  // Enqueued
state.name = 'Vue 3.6'  // Enqueued
state.count = 2  // Set deduplicates, same effect only enqueued once

// When the microtask executes, the effect runs only once
// Output: count: 2, name: Vue 3.6

The Vue 3.6 improvement is that queue changed from an array to a Set, providing natural deduplication and avoiding the issue of the same effect being enqueued multiple times. Additionally, 3.6 introduces an effect priority mechanism, ensuring component update effects execute before computed effects.

shallowRef and shallowReactive ​

typescript
function shallowRef<T>(value: T): Ref<T> {
  return new RefImpl(value, true) // __v_isShallow = true
}

function shallowReactive<T extends object>(target: T): T {
  return new Proxy(target, shallowReactiveHandlers)
}

// shallowReactive handlers
const shallowReactiveHandlers = {
  get(target, key, receiver) {
    if (key === '__v_isReactive') return true
    track(target, key)
    return Reflect.get(target, key, receiver)
    // Note: does not call reactive(res), nested objects remain raw
  },
  set(target, key, value, receiver) {
    const oldValue = target[key]
    const result = Reflect.set(target, key, value, receiver)
    if (hasChanged(value, oldValue)) {
      trigger(target, 'set', key, value, oldValue)
    }
    return result
  },
}

Use cases:

typescript
import { shallowRef, triggerRef } from 'vue'

// Large list data: only care about full replacement, not internal property changes
const list = shallowRef<Item[]>([])

// Replace entire list → triggers update
list.value = fetchNewList()

// Modify internal property → does not trigger update
list.value[0].name = 'new name' // ❌ Not reactive

// Manual trigger
list.value[0].name = 'new name'
triggerRef(list) // ✅ Manually notify update

Hand-Writing a Simplified Reactivity System ​

Integrating the above concepts into a runnable simplified version:

typescript
// ===== Simplified Reactivity System =====

let activeEffect: (() => void) | null = null
const targetMap = new WeakMap<object, Map<PropertyKey, Set<() => void>>>()

function track(target: object, key: PropertyKey) {
  if (!activeEffect) return
  let depsMap = targetMap.get(target)
  if (!depsMap) targetMap.set(target, (depsMap = new Map()))
  let dep = depsMap.get(key)
  if (!dep) depsMap.set(key, (dep = new Set()))
  dep.add(activeEffect)
}

function trigger(target: object, key: PropertyKey) {
  const depsMap = targetMap.get(target)
  if (!depsMap) return
  const dep = depsMap.get(key)
  if (dep) {
    for (const effect of [...dep]) {
      if (effect !== activeEffect) effect()
    }
  }
}

function reactive<T extends object>(target: T): T {
  return new Proxy(target, {
    get(target, key, receiver) {
      if (key === '__isReactive') return true
      const result = Reflect.get(target, key, receiver)
      track(target, key)
      if (result && typeof result === 'object') {
        return reactive(result)
      }
      return result
    },
    set(target, key, value, receiver) {
      const oldValue = (target as any)[key]
      const result = Reflect.set(target, key, value, receiver)
      if (oldValue !== value) {
        trigger(target, key)
      }
      return result
    },
  })
}

function ref<T>(value: T) {
  const wrapper = {
    get value() {
      track(wrapper, 'value')
      return value
    },
    set value(newVal: T) {
      if (newVal !== value) {
        value = newVal
        trigger(wrapper, 'value')
      }
    },
  }
  return wrapper
}

function effect(fn: () => void) {
  const run = () => {
    activeEffect = run
    try {
      fn()
    } finally {
      activeEffect = null
    }
  }
  run()
}

// ===== Usage Example =====

const state = reactive({ count: 0, name: 'Vue' })
const double = ref(0)

effect(() => {
  double.value = state.count * 2
  console.log(`count: ${state.count}, double: ${double.value}`)
})
// Output: count: 0, double: 0

state.count = 5
// Output: count: 5, double: 10

state.count = 10
// Output: count: 10, double: 20

Performance Comparison and Use Cases ​

In a scenario updating a list of 10,000 items (Vue 3.6 vs Vue 2.7):

MetricVue 2.7Vue 3.6
Initialization time120ms45ms
Single item update8ms1.5ms
Full update95ms28ms
Memory usage15MB9MB

Vue 3.6's performance advantage comes primarily from: Proxy's interception efficiency being higher than defineProperty, lazy reactivity avoiding full proxying at initialization, and the flattened dependency data structure reducing GC pressure.

Use Case Recommendations ​

  • reactive: Suitable for form state, configuration objects, and other structurally stable object data
  • ref: Suitable for primitives, objects that need full replacement, and dynamic data fetched from APIs
  • shallowReactive: Suitable for root objects of large lists, only tracking first-level property changes
  • shallowRef: Suitable for large data objects that don't need deep reactivity, combined with triggerRef for manual update control

Summary ​

Vue 3.6's reactivity system is built on the Proxy and effect tracking model. reactive intercepts the entire object through Proxy, supporting lazy nested reactivity; ref intercepts .value access through getter/setter, solving the problem that primitives cannot be proxied by Proxy. Dependency collection maintains the target → key → effect mapping through targetMap, and trigger finds and executes related effects by key. The batching mechanism is implemented through the microtask queue and Set deduplication, ensuring only one render per event loop. Understanding these underlying mechanisms is essential for making the right reactivity choices in complex scenarios and avoiding common reactivity pitfalls.

MIT Licensed