stack/packages/mosaic/framework/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