Vue.js: Pinia State Management

// ❌ The broken version: 5 components, 5 copies of the data
// CartIcon.vue
const cartCount = ref(0)

// ProductCard.vue
const localCart = ref([])

// CartPage.vue
const cart = ref({ items: [], total: 0 })

// CheckoutPage.vue
const myCart = ref([])

// Header.vue
const cartItems = ref([])

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

export const useCartStore = defineStore('cart', {
  state: () => ({
    items: [],
    total: 0
  }),
  getters: {
    itemCount: (state) => state.items.length,
    totalPrice: (state) => state.items.reduce((sum, i) => sum + i.price, 0)
  },
  actions: {
    addItem(product) {
      this.items.push(product)
      this.total += product.price
    },
    removeItem(id) {
      this.items = this.items.filter(i => i.id !== id)
    }
  }
})

<!-- CartIcon.vue -->
<script setup>
import { useCartStore } from '@/stores/cart'
const cart = useCartStore()
// Automatically reactive: when cart.itemCount changes, the icon updates at once
</script>
<template>
  <span>🛒 {{ cart.itemCount }}</span>
</template>

<!-- ProductCard.vue -->
<script setup>
import { useCartStore } from '@/stores/cart'
const cart = useCartStore()
</script>
<template>
  <button @click="cart.addItem(product)">Add to Cart</button>
</template>

// stores/counter.js
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  // state: data
  state: () => ({
    count: 0,
    name: 'Counter'
  }),
  
  // getters: derived values (like computed)
  getters: {
    doubleCount: (state) => state.count * 2,
    isZero: (state) => state.count === 0
  },
  
  // actions: methods (like methods)
  actions: {
    increment() {
      this.count++
    },
    async fetchData() {
      const res = await fetch('/api/count')
      this.count = await res.json()
    }
  }
})

// stores/auth.js
import { defineStore } from 'pinia'
const { ref, computed } = Vue

export const useAuthStore = defineStore('auth', () => {
  // 1. state (via ref)
  const user = ref(null)
  const token = ref(localStorage.getItem('token') || '')
  
  // 2. getters (via computed)
  const isLoggedIn = computed(() => !!token.value)
  const userName = computed(() => user.value?.name || 'Guest')
  
  // 3. actions (plain functions)
  function login(credentials) {
    // API call...
    user.value = { name: 'Alice' }
    token.value = 'xxx'
  }
  
  function logout() {
    user.value = null
    token.value = ''
  }
  
  return { user, token, isLoggedIn, userName, login, logout }
})

The root panel shows "count: 0 | doubleCount: 0 | isZero: true" and the child panel shows "count: 0 | doubleCount: 0".
Clicking the root "+1" twice moves both panels to count: 2 and doubleCount: 4, and isZero flips to false.
Clicking "Child +1" pushes the root to count: 3 and doubleCount: 6; clicking reset zeroes both at once and isZero returns to true.

// Options style
state: () => ({
  count: 0,
  user: null,
  items: []
})

// Setup style
const count = ref(0)
const user = ref(null)
const items = ref([])

// Options style
getters: {
  // a simple getter
  doubleCount: (state) => state.count * 2,
  
  // access another getter (through this)
  ratio(state) {
    return this.doubleCount / 100
  },
  
  // return a function (a parameterized getter)
  getItemById: (state) => (id) => {
    return state.items.find(i => i.id === id)
  }
}

// Setup style
const doubleCount = computed(() => count.value * 2)
const getItemById = (id) => items.value.find(i => i.id === id)

// Options style
actions: {
  // synchronous
  increment() {
    this.count++
  },
  
  // asynchronous
  async fetchData() {
    const res = await fetch('/api/data')
    this.data = await res.json()
  },
  
  // call other actions
  async loginAndFetch(credentials) {
    await this.login(credentials)
    await this.fetchUser()
  }
}

// Setup style
function increment() {
  count.value++
}
async function fetchData() {
  const res = await fetch('/api/data')
  data.value = await res.json()
}

<script setup>
import { useCartStore } from '@/stores/cart'
import { storeToRefs } from 'pinia'

const cart = useCartStore()

// 1. Access state directly (reactive)
console.log(cart.items)

// 2. Destructure with storeToRefs (stays reactive)
const { items, total } = storeToRefs(cart)

// 3. Call an action
cart.addItem(product)

// 4. Watch state changes
watch(() => cart.items, (newItems) => {
  console.log('Cart changed:', newItems)
})
</script>

// ⚠️ Note 1: destructuring state loses reactivity
const { items } = cart  // ❌ items is a plain value
const { items } = storeToRefs(cart)  // ✅ items is a ref

// ⚠️ Note 2: mutate state through an action
cart.items.push(...)  // ❌ not recommended (direct mutation)
cart.addItem(...)     // ✅ use an action

// ⚠️ Note 3: this inside an action points at the store
actions: {
  increment() {
    this.count++  // ✅ this = store
  }
}

// ⚠️ Note 4: getter caching
getters: {
  doubleCount() {
    console.log('recomputed')  // only logs when a dependency changes
    return this.count * 2
  }
}

// ⚠️ Note 5: outside setup, pass the pinia instance to useStore
import { getActivePinia } from 'pinia'
const cart = useCartStore(getActivePinia())  // inside a .js file

npm install pinia-plugin-persistedstate

// stores/cart.js
export const useCartStore = defineStore('cart', () => {
  const items = ref([])
  
  return { items }
}, {
  // 1. Default: the localStorage key is 'cart'
  persist: true,
  
  // 2. Custom key
  persist: {
    key: 'my-cart',
    storage: localStorage
  },
  
  // 3. Persist only part of the state
  persist: {
    paths: ['items']  // only items is saved, total is not
  },
  
  // 4. sessionStorage (cleared when the browser closes)
  persist: {
    storage: sessionStorage
  },
  
  // 5. Custom serialization (encryption, etc.)
  persist: {
    serializer: {
      serialize: (value) => btoa(JSON.stringify(value)),
      deserialize: (value) => JSON.parse(atob(value))
    }
  }
})

First open shows "Theme: light | Cart: 0 item(s)", the localStorage line reads (empty), and the child badge is 0.
"Toggle theme" switches the theme to dark; clicking "Add an item" twice makes the cart 2 items and the child badge 2.
The localStorage line updates live to {"theme":"dark","items":[{"id":1766...},{"id":1766...}]}.
Reload the page: the theme is still dark and the cart still holds 2 items (restored from the cache); "Clear cart" empties the items array.

Three bordered panels render at once.
Panels 1 and 2 show the same count/double numbers because they inject the same singleton store — clicking +1 in either panel updates both.
Panel 3 tracks its own cart store: the first click on "Add 1 iPhone" shows items: 1, total: $999, the next $1998, and "Clear" resets it to 0 / $0.

Panel 1  count: 0 | double: 0     Panel 2  count: 0 | double: 0
Click +1 in panel 2  ->  both panels: count: 1 | double: 2   (one shared store)
Click Reset in panel 1 -> both panels: count: 0 | double: 0
Panel 3  items: 0, total: $0
Add iPhone x2          ->  items: 2, total: $1998
Clear                  ->  items: 0, total: $0

A five-row reference table mapping each core API to its purpose and a one-line example — the fastest way to recall the surface area of a store.

Renders one table: 5 rows x 3 columns (API | Purpose | Example).

A five-row troubleshooting table covering the Pinia errors you are most likely to hit, from lost reactivity to missing plugin registration, each with its one-line fix.

Renders one table: 5 rows x 3 columns (Mistake | Symptom | Fix).

A five-row mapping table from business domain to store name and its key fields — a ready-made skeleton for splitting an app's global state into modular stores.

Renders one table: 5 rows x 3 columns (Scenario | Store | Key fields).