ContextQMD
Back to Airi

State Management Strategy

.agents/skills/vue-best-practices/references/state-management.md

0.10.13.0 KB
Original Source

State Management Strategy

Impact: HIGH - Use the lightest state solution that fits your app architecture. SPA-only apps can use lightweight global composables, while SSR/Nuxt apps should default to Pinia for request-safe isolation and predictable tooling.

Task List

  • Keep state local first, then promote to shared/global only when needed
  • Use singleton composables only in non-SSR applications
  • Expose global state as readonly and mutate through explicit actions
  • Prefer Pinia for SSR/Nuxt, large apps, and advanced debugging/plugin needs
  • Avoid exporting mutable module-level reactive state directly

Choose the Lightest Store Approach

  • Feature composable: Default for reusable logic with local/feature-level state.
  • Singleton composable or VueUse createGlobalState: Small non-SSR apps needing shared app state.
  • Pinia: SSR/Nuxt apps, medium-to-large apps, and cases requiring DevTools, plugins, or action tracing.

Avoid Exporting Mutable Module State

BAD:

ts
// store/cart.ts
import { reactive } from 'vue'

export const cart = reactive({
  items: [] as Array<{ id: string, qty: number }>
})

GOOD:

ts
// composables/useCartStore.ts
import { reactive, readonly } from 'vue'

let _store: ReturnType<typeof createCartStore> | null = null

function createCartStore() {
  const state = reactive({
    items: [] as Array<{ id: string, qty: number }>
  })

  function addItem(id: string, qty = 1) {
    const existing = state.items.find(item => item.id === id)
    if (existing) {
      existing.qty += qty
      return
    }
    state.items.push({ id, qty })
  }

  return {
    state: readonly(state),
    addItem
  }
}

export function useCartStore() {
  if (!_store)
    _store = createCartStore()
  return _store
}

Do Not Use Runtime Singletons in SSR

Module singletons live for the runtime lifetime. In SSR this can leak state between requests.

BAD:

ts
// shared singleton reused across requests
const cartStore = useCartStore()

export function useServerCart() {
  return cartStore
}

GOOD:

pinia dependency required.

ts
// stores/cart.ts
import { defineStore } from 'pinia'

export const useCartStore = defineStore('cart', {
  state: () => ({
    items: [] as Array<{ id: string, qty: number }>
  }),
  actions: {
    addItem(id: string, qty = 1) {
      const existing = this.items.find(item => item.id === id)
      if (existing) {
        existing.qty += qty
        return
      }
      this.items.push({ id, qty })
    }
  }
})

Use createGlobalState for Small SPA Global State

@vueuse/core dependency required.

If the app is non-SSR and already uses VueUse, createGlobalState removes singleton boilerplate.

ts
import { createGlobalState } from '@vueuse/core'
import { computed, ref } from 'vue'

export const useAuthState = createGlobalState(() => {
  const token = ref<string | null>(null)
  const isAuthenticated = computed(() => token.value !== null)

  function setToken(next: string | null) {
    token.value = next
  }

  return {
    token,
    isAuthenticated,
    setToken
  }
})