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

4.6 KiB Raw Blame History

Use shallowRef Pattern for External State Libraries

Task Checklist

Reference

4.6 KiB

Raw Blame History