secondsky/claude-skills / plugins/pinia-v3/skills/pinia-v3
pinia-v3
VerifiedPinia v3 Vue state management with defineStore, getters, actions. Use for Vue 3 stores, Nuxt SSR, Vuex migration, or encountering store composition, hydration, testing errors.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.5 KB |
| assets/example-template.txt | markdown | 425 B |
| references/example-reference.md | markdown | 760 B |
| references/plugins-composables.md | markdown | 9.7 KB |
| references/ssr-and-nuxt.md | markdown | 8.2 KB |
| references/state-getters-actions.md | markdown | 10.5 KB |
| references/store-syntax-guide.md | markdown | 6.2 KB |
| references/testing-guide.md | markdown | 9.6 KB |
| references/vuex-migration-checklist.md | markdown | 9.3 KB |
| references/vuex-migration.md | markdown | 9.9 KB |
| scripts/api-store-example.ts | script | 6.9 KB |
| scripts/auth-store-example.ts | script | 5.9 KB |
| scripts/example-script.shexecutable | script | 302 B |
| scripts/option-store-template.ts | script | 2.6 KB |
| scripts/persistence-plugin.ts | script | 7.9 KB |
| scripts/setup-store-template.ts | script | 2.7 KB |
references/state-getters-actions.md
View on GitHub# Pinia State, Getters, and Actions Guide
Complete API reference for managing state, computed properties, and business logic in Pinia stores.
**Last Updated**: 2025-11-21
---
## State Management
### Defining State
**Option Stores:**
```typescript
state: () => ({
count: 0,
name: 'Eduardo',
isAdmin: true,
items: [],
// Even undefined values must be declared
user: undefined as User | undefined
})
```
**Setup Stores:**
```typescript
const count = ref(0)
const name = ref('Eduardo')
const isAdmin = ref(true)
const items = ref<Item[]>([])
const user = ref<User>()
return { count, name, isAdmin, items, user }
```
**CRITICAL:**
- ALL state properties MUST be defined in `state()` or returned from setup
- Cannot add new state properties dynamically after store creation
- Use proper types for TypeScript inference
### Accessing State
Direct access - read and write:
```typescript
const store = useCounterStore()
// Read
console.log(store.count)
// Write
store.count++
store.name = 'Alice'
// Works with v-model
<input v-model="store.name" />
```
### Mutating State
**Method 1: Direct Mutation**
```typescript
store.count++
store.name = 'Alice'
```
**Method 2: $patch with Object**
```typescript
store.$patch({
count: store.count + 1,
name: 'Alice'
})
```
**Method 3: $patch with Function**
```typescript
// Best for complex mutations (arrays, etc.)
store.$patch((state) => {
state.items.push({ name: 'shoes', quantity: 1 })
state.hasChanged = true
})
```
### Resetting State
**Option Stores:**
```typescript
store.$reset() // Restores to initial state
```
**Setup Stores:**
```typescript
// Must implement manually
export const useCounterStore = defineStore('counter', () => {
const count = ref(0)
function $reset() {
count.value = 0
}
return { count, $reset }
})
```
### Subscribing to State Changes
```typescript
store.$subscribe((mutation, state) => {
// Called after each patch
console.log(mutation.type) // 'direct' | 'patch object' | 'patch function'
console.log(mutation.storeId) // 'counter'
console.log(mutation.payload) // patch object
// Persist to localStorage
localStorage.setItem('counter', JSON.stringify(state))
})
// Options
store.$subscribe(callback, {
detached: true // Keep subscription after component unmounts
})
store.$subscribe(callback, {
flush: 'sync' // Call immediately (instead of post-component-update)
})
```
---
## Getters (Computed State)
### Defining Getters
**Arrow Functions (Recommended):**
```typescript
getters: {
doubleCount: (state) => state.count * 2,
upperName: (state) => state.name.toUpperCase()
}
```
**Regular Functions:**
```typescript
getters: {
doubleCount(state) {
return state.count * 2
}
}
```
### Accessing Other Getters
**IMPORTANT**: When using `this`, must use regular function and type return value:
```typescript
getters: {
doubleCount: (state) => state.count * 2,
// Must type return when using 'this'
doublePlusOne(): number {
return this.doubleCount + 1
}
}
```
### Passing Arguments to Getters
Return a function from the getter:
```typescript
getters: {
getUserById: (state) => {
return (userId: number) => state.users.find(user => user.id === userId)
}
}
// Usage in component
<script setup>
import { storeToRefs } from 'pinia'
const store = useUserStore()
const { getUserById } = storeToRefs(store)
</script>
<template>
<p>User 2: {{ getUserById(2) }}</p>
</template>
```
**NOTE:** Returning functions prevents caching. Consider internal caching if performance matters.
### Accessing Other Stores' Getters
```typescript
import { useOtherStore } from './other-store'
getters: {
combinedData(state) {
const otherStore = useOtherStore()
return state.localData + otherStore.data
}
}
```
---
## Actions (Business Logic)
### Defining Actions
```typescript
actions: {
increment() {
this.count++
},
incrementBy(amount: number) {
this.count += amount
},
reset() {
this.count = 0
}
}
```
**NOTE:** Cannot use arrow functions (need `this` context)
### Async Actions
Actions can be async and await any promises:
```typescript
actions: {
async registerUser(login: string, password: string) {
try {
this.userData = await api.post({ login, password })
showToast('Registration successful')
} catch (error) {
showToast(error)
return error
}
},
async fetchUserPreferences() {
const auth = useAuthStore()
if (auth.isAuthenticated) {
this.preferences = await fetchPreferences()
}
}
}
```
### Accessing Other Store Actions
```typescript
actions: {
async loginAndLoad() {
const auth = useAuthStore()
await auth.login()
// After auth succeeds, load user data
await this.loadUserData()
}
}
```
### Subscribing to Actions
```typescript
const unsubscribe = store.$onAction(
({
name, // action name
store, // store instance
args, // array of action parameters
after, // hook after action returns/resolves
onError // hook if action throws/rejects
}) => {
const startTime = Date.now()
console.log(`Action "${name}" started with params:`, args)
after((result) => {
console.log(`Finished in ${Date.now() - startTime}ms`)
console.log('Result:', result)
})
onError((error) => {
console.error(`Failed: ${error}`)
})
}
)
// With second parameter true, subscription persists after component unmount
store.$onAction(callback, true)
```
---
## Store Destructuring with Reactivity
### Problem: Direct Destructuring Breaks Reactivity
```typescript
// ❌ DON'T DO THIS
const { name, count } = store // Loses reactivity!
```
### Solution: Use storeToRefs()
```typescript
import { storeToRefs } from 'pinia'
// ✅ Extract state/getters with reactivity
const { name, count, doubleCount } = storeToRefs(store)
// ✅ Actions can be destructured directly (no need for storeToRefs)
const { increment, reset } = store
// Now reactive in templates
<template>
<p>{{ name }}</p> <!-- Reactive -->
<button @click="increment">+</button>
</template>
```
---
## Store Composition
### Three Safe Patterns
**1. Nested Stores (Setup Pattern):**
```typescript
export const useCartStore = defineStore('cart', () => {
const user = useUserStore() // ✅ Top-level call
const items = ref([])
function addItem(item) {
items.value.push(item)
}
return { items, addItem, user }
})
```
**2. Shared Getters:**
```typescript
getters: {
userData() {
const user = useUserStore() // ✅ Inside getter
return user.data
}
}
```
**3. Shared Actions:**
```typescript
actions: {
async loadData() {
const user = useUserStore() // ✅ Inside action
if (user.isAuthenticated) {
this.data = await fetch('/data')
}
}
}
```
### ❌ Circular Dependencies to Avoid
```typescript
// ❌ NEVER: Both stores read each other's state at setup
export const useStoreA = defineStore('a', () => {
const storeB = useStoreB()
const value = storeB.value // ❌ Circular dependency
return { value }
})
export const useStoreB = defineStore('b', () => {
const storeA = useStoreA()
const value = storeA.value // ❌ Circular dependency
return { value }
})
```
### SSR Consideration for Async Actions
```typescript
actions: {
async loadData() {
// ✅ All useStore() calls BEFORE await
const authStore = useAuthStore()
const settingsStore = useSettingsStore()
// ❌ Don't call useStore() after await (breaks SSR)
const data = await fetch('/api')
// Store calls already made, safe to use
if (authStore.isAuthenticated) {
this.data = data
}
}
}
```
---
## Using Stores Outside Components
### The Problem
Stores need the Pinia instance, which is auto-injected in components but not available in module scope.
### ❌ Wrong: Accessing Store at Module Level
```typescript
// router.ts
import { useUserStore } from '@/stores/user'
// ❌ Fails: Pinia not installed yet
const userStore = useUserStore()
router.beforeEach((to) => {
if (userStore.isLoggedIn) { /* ... */ }
})
```
### ✅ Right: Accessing Store Inside Callbacks
```typescript
// router.ts
import { useUserStore } from '@/stores/user'
router.beforeEach((to) => {
// ✅ Works: Called after Pinia is installed
const userStore = useUserStore()
if (userStore.isLoggedIn) { /* ... */ }
})
```
**Why it works**: Router guards execute AFTER `app.use(pinia)` completes.
### SSR: Explicit Pinia Instance
```typescript
// server-side
export function setupRouter(pinia) {
router.beforeEach((to) => {
const userStore = useUserStore(pinia) // Pass explicitly
})
}
```
---
## Options API Usage
### With setup()
```vue
<script>
import { useCounterStore } from '@/stores/counter'
export default {
setup() {
const counterStore = useCounterStore()
return { counterStore }
},
methods: {
handleClick() {
this.counterStore.increment()
}
}
}
</script>
```
### Without setup() - Using Mappers
**mapStores:**
```vue
<script>
import { mapStores } from 'pinia'
import { useCounterStore, useUserStore } from '@/stores'
export default {
computed: {
...mapStores(useCounterStore, useUserStore)
// Adds this.counterStore and this.userStore
},
methods: {
handleClick() {
this.counterStore.increment()
}
}
}
</script>
```
**mapState (read-only):**
```vue
<script>
import { mapState } from 'pinia'
import { useCounterStore } from '@/stores/counter'
export default {
computed: {
...mapState(useCounterStore, ['count', 'doubleCount']),
// Adds this.count and this.doubleCount (read-only)
...mapState(useCounterStore, {
myCount: 'count',
myDouble: store => store.doubleCount
})
}
}
</script>
```
**mapWritableState (read-write):**
```vue
<script>
import { mapWritableState } from 'pinia'
import { useCounterStore } from '@/stores/counter'
export default {
computed: {
...mapWritableState(useCounterStore, ['count', 'name'])
// Can modify: this.count++
}
}
</script>
```
**mapActions:**
```vue
<script>
import { mapActions } from 'pinia'
import { useCounterStore } from '@/stores/counter'
export default {
methods: {
...mapActions(useCounterStore, ['increment', 'reset'])
// Adds this.increment() and this.reset()
}
}
</script>
```
**Customizing Store Suffix:**
```typescript
import { setMapStoreSuffix } from 'pinia'
setMapStoreSuffix('') // Remove 'Store' suffix
// ...mapStores(useCounter) -> this.counter (not this.counterStore)
setMapStoreSuffix('_store')
// ...mapStores(useCounter) -> this.counter_store
```
---
**See also:**
- `store-syntax-guide.md` for choosing between Option and Setup stores
- `plugins-composables.md` for advanced store enhancement
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |