agent-skills/skills/vue-best-practices/reference/reactivity-external-state-integration.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Use shallowRef Pattern for External State Libraries	MEDIUM	External state systems (Immer, XState, Redux) should use shallowRef to avoid double-wrapping in proxies	efficiency	vue3 reactivity shallowRef external-state immer xstate integration

Use shallowRef Pattern for External State Libraries

Impact: MEDIUM - When integrating Vue with external state management libraries (Immer, XState, Redux, MobX), use shallowRef() to hold the external state. This prevents Vue from deep-wrapping the external state in proxies, which can cause conflicts and performance issues.

The pattern: hold external state in a shallowRef, and replace .value entirely when the external system updates. This gives Vue reactivity while letting the external library manage state internals.

Task Checklist

• Use shallowRef() to hold external library state
• Replace .value entirely when external state changes (don't mutate)
• Integrate update functions that produce new state objects
• Consider this pattern for immutable data structures

Integrating with Immer:

import { produce } from 'immer'
import { shallowRef } from 'vue'

export function useImmer(baseState) {
  const state = shallowRef(baseState)

  function update(updater) {
    // Immer produces a new immutable state
    // Replace shallowRef value entirely to trigger reactivity
    state.value = produce(state.value, updater)
  }

  return [state, update]
}

// Usage
const [todos, updateTodos] = useImmer([
  { id: 1, text: 'Learn Vue', done: false }
])

// Update with Immer's mutable API (produces immutable result)
updateTodos(draft => {
  draft[0].done = true
  draft.push({ id: 2, text: 'Use Immer', done: false })
})

Integrating with XState:

import { createMachine, interpret } from 'xstate'
import { shallowRef, onUnmounted } from 'vue'

export function useMachine(options) {
  const machine = createMachine(options)
  const state = shallowRef(machine.initialState)

  const service = interpret(machine)
    .onTransition((newState) => {
      // Replace state entirely on each transition
      state.value = newState
    })
    .start()

  const send = (event) => service.send(event)

  onUnmounted(() => service.stop())

  return { state, send }
}

// Usage
const { state, send } = useMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: { on: { TOGGLE: 'active' } },
    active: { on: { TOGGLE: 'inactive' } }
  }
})

// In template: state.value.matches('active')
send('TOGGLE')

Integrating with Redux-style stores:

import { shallowRef, readonly } from 'vue'

export function createStore(reducer, initialState) {
  const state = shallowRef(initialState)

  function dispatch(action) {
    state.value = reducer(state.value, action)
  }

  function getState() {
    return state.value
  }

  return {
    state: readonly(state),  // Prevent direct mutations
    dispatch,
    getState
  }
}

// Usage
const store = createStore(
  (state, action) => {
    switch (action.type) {
      case 'INCREMENT':
        return { ...state, count: state.count + 1 }
      default:
        return state
    }
  },
  { count: 0 }
)

store.dispatch({ type: 'INCREMENT' })
console.log(store.state.value.count) // 1

Why NOT use ref() for external state:

import { ref } from 'vue'
import { produce } from 'immer'

// WRONG: ref() deep-wraps the state
const state = ref({ nested: { value: 1 } })

// This creates double-proxying:
// 1. Vue wraps state in Proxy
// 2. External library may also wrap/expect raw objects
// 3. Causes identity issues and potential conflicts

// WRONG: Mutating ref with Immer
state.value = produce(state.value, draft => {
  draft.nested.value = 2
})
// Vue's deep proxy on state.value may interfere with Immer's proxies

Correct pattern with shallowRef:

import { shallowRef } from 'vue'

// CORRECT: shallowRef only tracks .value replacement
const state = shallowRef({ nested: { value: 1 } })

// External library works with raw objects inside
state.value = produce(state.value, draft => {
  draft.nested.value = 2
})
// Clean separation: Vue tracks outer ref, library manages inner state

Reference

• Vue.js Reactivity in Depth - Integration with External State
• Vue.js shallowRef API
• Immer Documentation
• XState Documentation