web-state-pinia_skill

Overview

This skill documents Pinia state management patterns for Vue 3, covering Options vs Setup stores, store composition, persistence, DevTools, and SSR considerations. It focuses on practical rules and anti-patterns to prevent reactivity and hydration bugs. Use it to choose store styles, compose stores safely, and implement persistence correctly.

How this skill works

The skill inspects common Pinia usage patterns and enforces critical requirements: never store server/API responses in Pinia, always return all state refs from Setup stores, use storeToRefs() when destructuring, use named exports only, and avoid magic numbers by using named constants. It explains when to prefer Options stores or Setup stores, how to compose stores without circular dependencies, and how to add persistence and plugins safely.

When to use it

• Managing shared client state across a Vue 3 application (UI, preferences, feature flags).
• Choosing between Options stores (simplicity) and Setup stores (composables, watchers).
• Composing stores that depend on each other while avoiding circular references.
• Implementing persistence for non-sensitive client data across sessions.
• Preparing stores for SSR/Nuxt and DevTools-friendly inspection.

Best practices

• Never put server/API responses into Pinia; always use a dedicated data-fetching layer and cache there.
• When destructuring state in components, use storeToRefs() to preserve reactivity and computed getters.
• Return every state property from Setup stores so SSR and DevTools remain reliable.
• Use named exports only for all store files and define named constants instead of magic numbers.
• Persist only non-sensitive fields and restrict persisted keys with plugin paths options.

Example use cases

• A preferences store persisted to localStorage for theme and locale (no API data persisted).
• A filters store implemented as a Setup store to access router composables and sync query params.
• Composed stores where an auth store exposes user id and other stores import it safely at the top-level.
• A dashboard store using an external data-fetching client for API data while storing only UI state in Pinia.