1---
2title: State Management Strategy
3impact: HIGH
4impactDescription: Choosing the wrong store pattern can cause SSR request leaks, brittle mutation flows, and poor scaling
5type: best-practice
6tags: [vue3, state-management, pinia, composables, ssr, vueuse]
7---
8 
9# State Management Strategy
10 
11**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.
12 
13## Task List
14 
15- Keep state local first, then promote to shared/global only when needed
16- Use singleton composables only in non-SSR applications
17- Expose global state as readonly and mutate through explicit actions
18- Prefer Pinia for SSR/Nuxt, large apps, and advanced debugging/plugin needs
19- Avoid exporting mutable module-level reactive state directly
20 
21## Choose the Lightest Store Approach
22 
23- **Feature composable:** Default for reusable logic with local/feature-level state.
24- **Singleton composable or VueUse `createGlobalState`:** Small non-SSR apps needing shared app state.
25- **Pinia:** SSR/Nuxt apps, medium-to-large apps, and cases requiring DevTools, plugins, or action tracing.
26 
27## Avoid Exporting Mutable Module State
28 
29**BAD:**
30```ts
31// store/cart.ts
32import { reactive } from 'vue'
33 
34export const cart = reactive({
35  items: [] as Array<{ id: string; qty: number }>
36})
37```
38 
39**GOOD:**
40```ts
41// composables/useCartStore.ts
42import { reactive, readonly } from 'vue'
43 
44let _store: ReturnType<typeof createCartStore> | null = null
45 
46function createCartStore() {
47  const state = reactive({
48    items: [] as Array<{ id: string; qty: number }>
49  })
50 
51  function addItem(id: string, qty = 1) {
52    const existing = state.items.find((item) => item.id === id)
53    if (existing) {
54      existing.qty += qty
55      return
56    }
57    state.items.push({ id, qty })
58  }
59 
60  return {
61    state: readonly(state),
62    addItem
63  }
64}
65 
66export function useCartStore() {
67  if (!_store) _store = createCartStore()
68  return _store
69}
70```
71 
72## Do Not Use Runtime Singletons in SSR
73 
74Module singletons live for the runtime lifetime. In SSR this can leak state between requests.
75 
76**BAD:**
77```ts
78// shared singleton reused across requests
79const cartStore = useCartStore()
80 
81export function useServerCart() {
82  return cartStore
83}
84```
85 
86**GOOD:**
87 
88> `pinia` dependency required.
89 
90```ts
91// stores/cart.ts
92import { defineStore } from 'pinia'
93 
94export const useCartStore = defineStore('cart', {
95  state: () => ({
96    items: [] as Array<{ id: string; qty: number }>
97  }),
98  actions: {
99    addItem(id: string, qty = 1) {
100      const existing = this.items.find((item) => item.id === id)
101      if (existing) {
102        existing.qty += qty
103        return
104      }
105      this.items.push({ id, qty })
106    }
107  }
108})
109```
110 
111## Use `createGlobalState` for Small SPA Global State
112 
113> `@vueuse/core` dependency required.
114 
115If the app is non-SSR and already uses VueUse, `createGlobalState` removes singleton boilerplate.
116 
117```ts
118import { createGlobalState } from '@vueuse/core'
119import { computed, ref } from 'vue'
120 
121export const useAuthState = createGlobalState(() => {
122  const token = ref<string | null>(null)
123  const isAuthenticated = computed(() => token.value !== null)
124 
125  function setToken(next: string | null) {
126    token.value = next
127  }
128 
129  return {
130    token,
131    isAuthenticated,
132    setToken
133  }
134})
135```
136