Vue Pinia

Vue + Pinia

Pinia is the standard state management library for Vue 3, and setup stores built with the Composition API give shared application state the same ergonomics as local ref/computed state.

Workflow for Adding a Pinia Store

1. Decide if Pinia is the right tool — Confirm the state is shared across routes/components, not server cache data, and not purely local UI state (see State Ownership below).
2. Create the store file — Add one file per domain under stores/, e.g. stores/cart.ts, using defineStore('cart', () => { ... }).
3. Define state, getters, and actions — Declare state with ref/reactive, derive values with computed, and put all writes/side effects in functions (actions).
4. Return everything from the setup function — Return every piece of state, every getter, and every action so Pinia devtools, SSR, and plugins can track them.
5. Consume in components — Call the store at the top of <script setup>, destructure reactive state with storeToRefs(), and destructure actions directly.
6. Handle SSR/router-guard usage — Call the store from inside setup, a getter, an action, or pass the active Pinia instance explicitly outside setup contexts.
7. Add persistence and tests — Allowlist persisted fields, validate rehydrated data, and test actions directly with @pinia/testing.

State Ownership

• Keep component-only state in the component with ref, reactive, or computed.
• Use Pinia for shared client state that spans routes, layouts, or unrelated component trees.
• Use route params and query strings for shareable navigation state — don't duplicate it into a store.
• Use Nuxt useFetch / useAsyncData, TanStack Query for Vue, or the existing API layer for server state — Pinia is for client state, not a data-fetching cache.
• Do not copy server cache data into Pinia unless it is an intentional editable draft, offline cache, or workflow snapshot with its own lifecycle.

Store Structure

• Prefer setup stores with defineStore('name', () => { ... }) for Vue 3 Composition API projects over the older options-API defineStore({ state, getters, actions }) form.
• Use one store file per domain under stores/, such as stores/cart.ts or stores/session.ts.
• Keep state, computed getters, and actions together when they represent one cohesive domain.
• Return every state property from setup stores so Pinia can track it for devtools, SSR, and plugins — an un-returned ref is invisible to the rest of the system.
• Keep getters pure and side-effect free; put writes, I/O, and orchestration in actions.

// stores/cart.ts
import { computed, ref } from 'vue'
import { defineStore } from 'pinia'

interface CartLine {
  id: string
  name: string
  quantity: number
  unitPrice: number
}

export const useCartStore = defineStore('cart', () => {
  const lines = ref<CartLine[]>([])

  const itemCount = computed(() =>
    lines.value.reduce((total, line) => total + line.quantity, 0),
  )

  const subtotal = computed(() =>
    lines.value.reduce((total, line) => total + line.quantity * line.unitPrice, 0),
  )

  function addLine(line: CartLine) {
    const existing = lines.value.find((item) => item.id === line.id)
    if (existing) {
      existing.quantity += line.quantity
      return
    }
    lines.value.push(line)
  }

  function removeLine(id: string) {
    lines.value = lines.value.filter((line) => line.id !== id)
  }

  function clearCart() {
    lines.value = []
  }

  return {
    lines,
    itemCount,
    subtotal,
    addLine,
    removeLine,
    clearCart,
  }
})

Component Usage

• Call stores at the top of <script setup> or inside setup functions, getters, and actions — never conditionally, and never inside a plain .js/.ts module loaded at import time.
• Use storeToRefs() when destructuring store state or getters in components, so reactivity is preserved.
• Destructure actions directly when useful; actions remain bound to the store and don't need storeToRefs().
• Avoid writing large business workflows in components; move them to store actions or composables so they're testable and reusable.
• Prefer computed values over watchers when deriving state — a watch that just recomputes a value should usually be a computed.

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

const cart = useCartStore()
const { itemCount, subtotal } = storeToRefs(cart)
const { clearCart } = cart
</script>

<template>
  <div>
    <p>{{ itemCount }} items — ${{ subtotal.toFixed(2) }}</p>
    <button type="button" :disabled="itemCount === 0" @click="clearCart">
      Clear cart
    </button>
  </div>
</template>

TypeScript

• Type store state, action payloads, and API responses explicitly.
• Avoid any; use unknown and narrow external inputs (API responses, persisted storage) before committing them to state.
• Use interfaces for object state that is shared across components or API boundaries.
• Prefer discriminated unions for workflow status and error state, e.g. { status: 'idle' } | { status: 'loading' } | { status: 'error'; error: string }.
• Keep store IDs (the first argument to defineStore) stable and descriptive because they appear in devtools and persistence keys.

Actions and Side Effects

• Actions may be sync or async; keep each action focused on one user or domain workflow.
• Validate action inputs at the boundary before mutating store state.
• Represent async workflows with explicit status, error, and lastUpdatedAt fields when the UI depends on them.
• Reset stale errors before retrying an async action so a previous failure doesn't linger in the UI.
• Keep subscriptions, intervals, sockets, and browser listeners outside stores unless the store owns their lifecycle and cleanup (e.g. an explicit connect()/disconnect() action pair).