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

---
title: Use shallowRef Pattern for External State Libraries
impact: MEDIUM
impactDescription: External state systems (Immer, XState, Redux) should use shallowRef to avoid double-wrapping in proxies
type: efficiency
tags: [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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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](https://vuejs.org/guide/extras/reactivity-in-depth.html#integration-with-external-state-systems)
- [Vue.js shallowRef API](https://vuejs.org/api/reactivity-advanced.html#shallowref)
- [Immer Documentation](https://immerjs.github.io/immer/)
- [XState Documentation](https://xstate.js.org/)