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/vuex-migration.md
View on GitHub# Migrating from Vuex to Pinia
Complete guide for migrating existing Vuex applications to Pinia.
**Last Updated**: 2025-11-21
---
## Directory Structure Change
**Vuex:**
```
src/store/
├── index.js
└── modules/
├── user.js
├── cart.js
└── nested/
└── settings.js
```
**Pinia:**
```
src/stores/
├── user.ts
├── cart.ts
└── nested-settings.ts
```
**Key difference:** Each module becomes an independent store.
---
## Conversion Steps
### 1. Remove Module Namespacing
Module namespacing is built into Pinia store IDs.
**Vuex:**
```typescript
// modules/user.js
export default {
namespaced: true,
state: () => ({ ... })
}
```
**Pinia:**
```typescript
// stores/user.ts
export const useUserStore = defineStore('user', {
state: () => ({ ... })
})
```
---
### 2. Convert State to Function
Pinia requires state to be a function.
**Vuex (object state):**
```typescript
state: {
firstName: '',
lastName: ''
}
```
**Pinia (function state):**
```typescript
state: () => ({
firstName: '',
lastName: ''
})
```
---
### 3. Remove Identity Getters
Vuex often had getters that just returned state.
**Vuex:**
```typescript
// ❌ Remove these
getters: {
firstName: state => state.firstName
}
```
**Pinia:**
In Pinia, just access `store.firstName` directly. No getter needed.
---
### 4. Replace rootState/rootGetters
Use direct store imports instead of root access.
**Vuex:**
```typescript
getters: {
fullData(state, getters, rootState, rootGetters) {
return rootGetters['otherModule/data'] + state.local
}
}
```
**Pinia:**
```typescript
import { useOtherStore } from './other'
getters: {
fullData(state) {
const other = useOtherStore()
return other.data + state.local
}
}
```
---
### 5. Convert Actions
Remove context parameter and use direct mutations.
**Vuex:**
```typescript
actions: {
updateUser({ commit, state, dispatch, rootState }, payload) {
commit('SET_USER', payload)
dispatch('otherModule/action', null, { root: true })
}
}
```
**Pinia:**
```typescript
import { useOtherStore } from './other'
actions: {
updateUser(payload) {
this.user = payload // Direct mutation
const other = useOtherStore()
other.someAction() // Direct call
}
}
```
---
### 6. Eliminate Mutations
Pinia doesn't need mutations - mutate state directly.
**Vuex:**
```typescript
mutations: {
SET_USER(state, user) {
state.user = user
}
}
actions: {
updateUser({ commit }, user) {
commit('SET_USER', user)
}
}
```
**Pinia (Option 1 - Action mutation):**
```typescript
actions: {
updateUser(user) {
this.user = user // No mutation needed
}
}
```
**Pinia (Option 2 - Component mutation):**
```typescript
// Component
store.user = newUser // Directly mutate (acceptable in Pinia)
```
---
### 7. Use $reset() Instead of Custom Clear
**Vuex:**
```typescript
mutations: {
CLEAR_STATE(state) {
state.user = null
state.data = []
}
}
```
**Pinia:**
```typescript
store.$reset() // Returns to initial state
```
---
## Component Migration
### Composition API
**Vuex:**
```vue
<script>
import { mapState, mapActions } from 'vuex'
export default {
computed: {
...mapState('user', ['firstName', 'lastName'])
},
methods: {
...mapActions('user', ['updateUser'])
}
}
</script>
```
**Pinia:**
```vue
<script setup>
import { storeToRefs } from 'pinia'
import { useUserStore } from '@/stores/user'
const userStore = useUserStore()
const { firstName, lastName } = storeToRefs(userStore)
const { updateUser } = userStore
</script>
```
---
### Options API
**Vuex:**
```vue
<script>
import { mapState, mapActions } from 'vuex'
export default {
computed: {
...mapState('user', ['firstName', 'lastName'])
},
methods: {
...mapActions('user', ['updateUser'])
}
}
</script>
```
**Pinia:**
```vue
<script>
import { mapState, mapActions } from 'pinia'
import { useUserStore } from '@/stores/user'
export default {
computed: {
...mapState(useUserStore, ['firstName', 'lastName'])
},
methods: {
...mapActions(useUserStore, ['updateUser'])
}
}
</script>
```
---
## Complete Migration Example
### Vuex Store
```typescript
// store/modules/user.js
export default {
namespaced: true,
state: {
firstName: '',
lastName: '',
age: 0
},
getters: {
fullName: state => `${state.firstName} ${state.lastName}`,
isAdult: state => state.age >= 18
},
mutations: {
SET_FIRST_NAME(state, name) {
state.firstName = name
},
SET_LAST_NAME(state, name) {
state.lastName = name
},
SET_AGE(state, age) {
state.age = age
}
},
actions: {
async loadUser({ commit }, userId) {
const response = await fetch(`/api/users/${userId}`)
const user = await response.json()
commit('SET_FIRST_NAME', user.firstName)
commit('SET_LAST_NAME', user.lastName)
commit('SET_AGE', user.age)
},
updateFirstName({ commit }, name) {
commit('SET_FIRST_NAME', name)
}
}
}
```
### Pinia Store (Option Store)
```typescript
// stores/user.ts
import { defineStore } from 'pinia'
export const useUserStore = defineStore('user', {
state: () => ({
firstName: '',
lastName: '',
age: 0
}),
getters: {
fullName: (state) => `${state.firstName} ${state.lastName}`,
isAdult: (state) => state.age >= 18
},
actions: {
async loadUser(userId: number) {
const response = await fetch(`/api/users/${userId}`)
const user = await response.json()
// Direct mutations - no commits needed
this.firstName = user.firstName
this.lastName = user.lastName
this.age = user.age
},
updateFirstName(name: string) {
this.firstName = name
}
}
})
```
### Pinia Store (Setup Store)
```typescript
// stores/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
export const useUserStore = defineStore('user', () => {
// State
const firstName = ref('')
const lastName = ref('')
const age = ref(0)
// Getters
const fullName = computed(() => `${firstName.value} ${lastName.value}`)
const isAdult = computed(() => age.value >= 18)
// Actions
async function loadUser(userId: number) {
const response = await fetch(`/api/users/${userId}`)
const user = await response.json()
firstName.value = user.firstName
lastName.value = user.lastName
age.value = user.age
}
function updateFirstName(name: string) {
firstName.value = name
}
return {
firstName,
lastName,
age,
fullName,
isAdult,
loadUser,
updateFirstName
}
})
```
---
## Vuex Features and Pinia Equivalents
| Vuex Feature | Pinia Equivalent |
|--------------|------------------|
| `state` | `state()` (option) or `ref()` (setup) |
| `getters` | `getters` (option) or `computed()` (setup) |
| `mutations` | ❌ Not needed - mutate directly |
| `actions` | `actions` (option) or `function()` (setup) |
| `namespaced: true` | Automatic (store ID) |
| `rootState` | Import other stores |
| `rootGetters` | Import other stores |
| `commit()` | Direct mutation |
| `dispatch()` | Call action directly |
| `mapState` | `storeToRefs()` or `mapState()` |
| `mapGetters` | `storeToRefs()` or `mapState()` |
| `mapMutations` | ❌ Not needed |
| `mapActions` | `mapActions()` or destructure |
| `modules` | Independent stores |
| `registerModule` | Create new store dynamically |
---
## Migration Checklist
- [ ] Install Pinia: `bun add pinia`
- [ ] Create `stores/` directory
- [ ] Convert each Vuex module to a Pinia store
- [ ] Remove `namespaced` property (automatic in Pinia)
- [ ] Convert state to function if needed
- [ ] Remove identity getters
- [ ] Replace `rootState`/`rootGetters` with store imports
- [ ] Remove mutations, merge into actions
- [ ] Update actions to mutate state directly
- [ ] Convert components from Vuex helpers to Pinia
- [ ] Replace `commit()` calls with direct mutations
- [ ] Replace `dispatch()` calls with direct action calls
- [ ] Test all functionality
- [ ] Remove Vuex from `package.json`
- [ ] Delete `store/` directory
---
## Common Migration Pitfalls
### Pitfall 1: Forgetting to Use storeToRefs()
```vue
<!-- ❌ Wrong - loses reactivity -->
<script setup>
const { firstName, lastName } = useUserStore()
</script>
<!-- ✅ Correct - maintains reactivity -->
<script setup>
import { storeToRefs } from 'pinia'
const { firstName, lastName } = storeToRefs(useUserStore())
</script>
```
### Pitfall 2: Trying to Commit Mutations
```typescript
// ❌ Vuex habits die hard
actions: {
updateUser(user) {
this.commit('SET_USER', user) // No commit in Pinia!
}
}
// ✅ Mutate directly
actions: {
updateUser(user) {
this.user = user
}
}
```
### Pitfall 3: Not Converting Nested Modules
Don't forget to convert deeply nested Vuex modules:
```
store/modules/user/profile.js → stores/user-profile.ts
```
---
## Gradual Migration Strategy
### Step 1: Install Pinia Alongside Vuex
```typescript
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import store from './store' // Vuex store
const app = createApp(App)
const pinia = createPinia()
app.use(store) // Keep Vuex
app.use(pinia) // Add Pinia
app.mount('#app')
```
### Step 2: Migrate One Module at a Time
Convert one Vuex module to Pinia, test thoroughly, then move to next module.
### Step 3: Remove Vuex When Complete
```typescript
// Remove Vuex
// app.use(store)
// Keep only Pinia
app.use(pinia)
```
---
## Benefits After Migration
**What you gain:**
- ✅ Simpler API (no mutations, no namespacing)
- ✅ Better TypeScript support
- ✅ Smaller bundle size
- ✅ Automatic code splitting per store
- ✅ DevTools with time-travel debugging
- ✅ Hot module replacement (HMR)
- ✅ Plugin system
- ✅ SSR support out of the box
**What you lose:**
- ❌ Nothing! Pinia is a complete replacement
---
**See also:**
- `store-syntax-guide.md` for choosing Option vs Setup stores
- `state-getters-actions.md` for complete Pinia API
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 |