Pinia State skill for Codex

Done well means: each store owns one domain, holds only state that is truly shared, exposes derived data as getters, keeps side effects in actions, and has unit tests that run without mounting the app. Components read through storeToRefs and never reach into another store’s internals.

Inspect first

1. Read AGENTS.md, package.json (pinia 2.x supports Vue 2 and 3; 3.x is Vue 3 only) and where createPinia() is installed (main.ts, or @pinia/nuxt in nuxt.config.ts).
2. List existing stores (src/stores/, stores/ in Nuxt). Match their style: if the repo uses setup stores, write setup stores.
3. Check for plugins: pinia-plugin-persistedstate, custom pinia.use(...).

What belongs in a store

State	Where
Used by one component or its children	Component ref / provide
Server data (lists, details, pagination)	Data-fetching layer (useFetch, TanStack Query for Vue); a store only if many unrelated views mutate it
Session user, permissions, feature flags	Store
Cart, multi-step wizard spanning routes	Store
Form drafts	Component state; a store only if it must survive navigation
URL-shaped state (filters, page, tab)	Route query, not a store

Caching server responses in a store without invalidation rules is the most common source of stale UI. Decide who refreshes it before you add it.

Setup store (default)

// stores/cart.ts
import { defineStore, acceptHMRUpdate } from "pinia";
import { ref, computed } from "vue";

export interface CartLine { sku: string; qty: number; unitPrice: number }

export const useCartStore = defineStore("cart", () => {
  const lines = ref<CartLine[]>([]);
  const status = ref<"idle" | "saving" | "error">("idle");
  const error = ref<string | null>(null);

  const count = computed(() => lines.value.reduce((n, l) => n + l.qty, 0));
  const subtotal = computed(() => lines.value.reduce((s, l) => s + l.qty * l.unitPrice, 0));

  function add(line: CartLine) {
    const found = lines.value.find((l) => l.sku === line.sku);
    if (found) found.qty += line.qty;
    else lines.value.push({ ...line });
  }

  async function checkout(api: { submit(lines: CartLine[]): Promise<void> }) {
    status.value = "saving";
    error.value = null;
    try {
      await api.submit(lines.value);
      lines.value = [];
      status.value = "idle";
    } catch (e) {
      status.value = "error";
      error.value = e instanceof Error ? e.message : "Checkout failed";
      throw e;
    }
  }

  function $reset() {
    lines.value = [];
    status.value = "idle";
    error.value = null;
  }

  return { lines, status, error, count, subtotal, add, checkout, $reset };
});

if (import.meta.hot) import.meta.hot.accept(acceptHMRUpdate(useCartStore, import.meta.hot));

Setup store rules:

• Return every piece of state. Unreturned refs are invisible to DevTools, SSR serialization and plugins, and break hydration.
• $reset exists automatically only on option stores; write your own in setup stores.
• inject(), useRoute() and other composables work inside the setup function; they run once when the store is first used.
• Keep state serializable (no class instances, DOM nodes or functions in refs) if the app uses SSR or persistence.

Use an option store (state, getters, actions) when the team prefers it or for simple stores migrated from Vuex; do not mix styles within one repo without reason.

Using stores in components

const cart = useCartStore();
const { lines, count, subtotal, status } = storeToRefs(cart); // state + getters stay reactive
const { add, checkout } = cart;                              // actions destructure directly

• Destructuring state without storeToRefs copies values once and loses reactivity.
• Bulk updates: cart.$patch((s) => { s.lines.push(a, b) }) produces one subscription event.
• Cross-store access: call useOtherStore() inside an action or getter, not at the top of the setup function when two stores reference each other (circular init).
• Outside components (router guards, plugins), call useXStore(pinia) with the instance, or only after app.use(pinia) has run.

SSR and Nuxt

• With @pinia/nuxt, stores are auto-imported and state is serialized into the payload. Fetch inside the page with await callOnce('cart', () => cart.load()) or useAsyncData so the server fills it once.
• Never create a store at module scope (const cart = useCartStore() outside a function) in SSR code: it binds to the first request’s Pinia and leaks state between users.
• Persistence (pinia-plugin-persistedstate) reads from storage only on the client; expect the server render to use defaults and avoid rendering persisted values before mount, or you get hydration mismatches.

Migrating from Vuex

Move one module at a time; the two can coexist.

Vuex	Pinia
module with namespaced: true	one store per module, id = old namespace
state	state / ref
getters	getters / computed
mutations + actions	actions only (mutate state directly)
commit('x', p) / dispatch('y', p)	store.x(p)
mapState, mapGetters	storeToRefs (or mapState from pinia for Options API)
rootState	import and call the other store

Testing

Unit test a store directly:

import { setActivePinia, createPinia } from "pinia";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { useCartStore } from "@/stores/cart";

describe("cart store", () => {
  beforeEach(() => setActivePinia(createPinia())); // fresh state per test

  it("merges lines with the same sku", () => {
    const cart = useCartStore();
    cart.add({ sku: "A", qty: 1, unitPrice: 5 });
    cart.add({ sku: "A", qty: 2, unitPrice: 5 });
    expect(cart.lines).toHaveLength(1);
    expect(cart.subtotal).toBe(15);
  });

  it("keeps lines and records the error when checkout fails", async () => {
    const cart = useCartStore();
    cart.add({ sku: "A", qty: 1, unitPrice: 5 });
    const api = { submit: vi.fn().mockRejectedValue(new Error("card declined")) };
    await expect(cart.checkout(api)).rejects.toThrow();
    expect(cart.status).toBe("error");
    expect(cart.lines).toHaveLength(1);
  });
});

Component tests with a mocked store (@pinia/testing):

import { mount } from "@vue/test-utils";
import { createTestingPinia } from "@pinia/testing";

const wrapper = mount(CartBadge, {
  global: {
    plugins: [createTestingPinia({ createSpy: vi.fn, initialState: { cart: { lines: [{ sku: "A", qty: 3, unitPrice: 1 }] } } })],
  },
});
const cart = useCartStore();          // after mount
expect(wrapper.text()).toContain("3");
await wrapper.find("button").trigger("click");
expect(cart.add).toHaveBeenCalled();  // actions are stubbed by default

• Actions are stubbed in createTestingPinia; pass stubActions: false to run them.
• Getters are computed from initialState; override with cart.count = 99 in tests (writable in testing pinia only) when you need a specific value.
• Pass createSpy: vi.fn unless Vitest globals are enabled.

Verification

npx vue-tsc --noEmit
npx vitest run stores/

• Vue DevTools Pinia tab: state shows all returned fields, actions appear in the timeline.
• For SSR apps, open two browsers with different users and confirm no shared state.

Output

Report each store’s id, what state it owns and why it is global, the actions with side effects, persistence settings, and the tests added.