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-checklist.md
View on GitHub# Vuex to Pinia Migration Checklist
Complete checklist for migrating from Vuex to Pinia safely and efficiently.
---
## Pre-Migration Preparation
- [ ] **Document current Vuex setup**
- List all modules and their responsibilities
- Document any complex state dependencies
- Note any Vuex plugins in use
- [ ] **Install Pinia alongside Vuex**
```bash
bun add pinia
# or: npm install pinia
```
- [ ] **Set up Pinia instance**
```typescript
// main.ts
import { createPinia } from 'pinia'
const pinia = createPinia()
app.use(pinia) // Can coexist with Vuex initially
```
- [ ] **Choose migration strategy**
- [ ] Big bang (all at once)
- [ ] Incremental (module by module)
- [ ] Recommended: **Incremental migration**
---
## Module-by-Module Migration
### Step 1: Directory Structure
**Before (Vuex):**
```text
src/store/
├── index.js
└── modules/
├── auth/
│ └── index.js
├── cart/
│ └── index.js
└── products/
└── index.js
```
**After (Pinia):**
```text
src/stores/
├── auth.ts
├── cart.ts
└── products.ts
```
- [ ] Create `src/stores/` directory
- [ ] Plan naming convention: `use[Module]Store`
### Step 2: Module Conversion
For each Vuex module, complete this checklist:
- [ ] **Create Pinia store file**
- File: `stores/[module-name].ts`
- Export: `use[ModuleName]Store`
- [ ] **Convert state**
- [ ] Change from object to function: `state: () => ({ ... })`
- [ ] Declare all properties (no dynamic properties)
- [ ] Add TypeScript interfaces
- [ ] **Convert getters**
- [ ] Remove identity getters (direct state access)
- [ ] Convert `rootState`/`rootGetters` to store imports
- [ ] Add return types for getters using `this`
- [ ] **Convert actions**
- [ ] Remove `{ commit, dispatch, rootState }` parameter
- [ ] Change `commit('MUTATION')` to `this.property = value`
- [ ] Convert `dispatch('module/action')` to `useOtherStore().action()`
- [ ] Change `rootState.module` to `useModuleStore()`
- [ ] **Delete mutations**
- [ ] Move logic to actions
- [ ] Use direct state mutation: `this.count++`
- [ ] Use `$patch()` for multiple mutations
- [ ] **Add HMR support**
```typescript
if (import.meta.hot) {
import.meta.hot.accept(acceptHMRUpdate(useMyStore, import.meta.hot))
}
```
### Step 3: Component Updates
For each component using the migrated module:
- [ ] **Composition API components**
```typescript
// Before
import { useStore } from 'vuex'
const store = useStore()
const user = computed(() => store.state.auth.user)
// After
import { useAuthStore } from '@/stores/auth'
import { storeToRefs } from 'pinia'
const auth = useAuthStore()
const { user } = storeToRefs(auth)
```
- [ ] **Options API components**
```typescript
// Before
import { mapState, mapActions } from 'vuex'
computed: {
...mapState('auth', ['user'])
}
// After
import { mapState, mapActions } from 'pinia'
import { useAuthStore } from '@/stores/auth'
computed: {
...mapState(useAuthStore, ['user'])
}
```
- [ ] **Update all imports**
- [ ] **Test component functionality**
---
## Common Conversion Patterns
### Pattern 1: Namespaced Modules
**Vuex:**
```typescript
// store/modules/user.js
export default {
namespaced: true,
state: () => ({ ... }),
mutations: { ... },
actions: { ... }
}
```
**Pinia:**
```typescript
// stores/user.ts
export const useUserStore = defineStore('user', {
state: () => ({ ... }),
actions: { ... } // No namespaced needed - built-in
})
```
- [ ] Remove `namespaced: true`
- [ ] Store ID is the namespace
### Pattern 2: Root State Access
**Vuex:**
```typescript
getters: {
userData(state, getters, rootState) {
return rootState.settings.theme + state.name
}
}
```
**Pinia:**
```typescript
import { useSettingsStore } from './settings'
getters: {
userData(state) {
const settings = useSettingsStore()
return settings.theme + state.name
}
}
```
- [ ] Import other stores
- [ ] Replace `rootState.x` with `useXStore()`
### Pattern 3: Mutations → Direct Mutations
**Vuex:**
```typescript
mutations: {
SET_USER(state, user) {
state.user = user
},
INCREMENT(state) {
state.count++
}
}
actions: {
updateUser({ commit }, user) {
commit('SET_USER', user)
}
}
```
**Pinia:**
```typescript
actions: {
updateUser(user) {
this.user = user // Direct mutation
},
increment() {
this.count++
}
}
```
- [ ] Delete all mutations
- [ ] Move mutation logic to actions
- [ ] Use `this.property = value`
### Pattern 4: Module Registration
**Vuex:**
```typescript
// store/index.js
import user from './modules/user'
import cart from './modules/cart'
export default createStore({
modules: {
user,
cart
}
})
```
**Pinia:**
```typescript
// No central registration needed!
// Just import stores where needed
import { useUserStore } from '@/stores/user'
import { useCartStore } from '@/stores/cart'
```
- [ ] Remove module registration
- [ ] Stores auto-register on first use
---
## Testing Migration
- [ ] **Unit test stores**
```typescript
import { setActivePinia, createPinia } from 'pinia'
import { useAuthStore } from '@/stores/auth'
describe('Auth Store', () => {
beforeEach(() => {
setActivePinia(createPinia())
})
it('logs in user', async () => {
const auth = useAuthStore()
await auth.login({ email: 'test@test.com', password: '123' })
expect(auth.isAuthenticated).toBe(true)
})
})
```
- [ ] **Update component tests**
```typescript
import { createTestingPinia } from '@pinia/testing'
mount(MyComponent, {
global: {
plugins: [createTestingPinia()]
}
})
```
---
## Router Integration Updates
- [ ] **Update navigation guards**
**Vuex:**
```typescript
import store from '@/store'
router.beforeEach((to, from) => {
if (to.meta.requiresAuth && !store.state.auth.isAuthenticated) {
return '/login'
}
})
```
**Pinia:**
```typescript
import { useAuthStore } from '@/stores/auth'
router.beforeEach((to, from) => {
const auth = useAuthStore() // ✅ Call inside guard
if (to.meta.requiresAuth && !auth.isAuthenticated) {
return '/login'
}
})
```
---
## Plugin Migration
- [ ] **Audit Vuex plugins**
- List all plugins currently in use
- Check if Pinia equivalents exist
- Plan custom plugin conversions
- [ ] **Common plugin conversions**
**Vuex Persistence:**
```typescript
// Vuex
import createPersistedState from 'vuex-persistedstate'
createStore({
plugins: [createPersistedState()]
})
```
**Pinia Persistence:**
```typescript
// Pinia
import { persistPlugin } from '@/plugins/persist'
const pinia = createPinia()
pinia.use(persistPlugin)
```
---
## Performance Optimization
- [ ] **Enable DevTools**
- Verify Pinia appears in Vue DevTools
- Test time-travel debugging
- [ ] **Add HMR to all stores**
- Faster development iteration
- Preserve state during edits
- [ ] **Remove unused code**
- Delete Vuex store files
- Remove Vuex from package.json (when fully migrated)
- Remove Vuex setup from main.ts
---
## Final Cleanup
- [ ] **Remove Vuex completely**
```bash
bun remove vuex
# or: npm uninstall vuex
```
- [ ] **Delete Vuex files**
- Remove `store/` directory
- Remove Vuex TypeScript declarations
- [ ] **Update documentation**
- Update README with Pinia setup
- Document new store patterns
- Update contribution guidelines
- [ ] **Team training**
- Share Pinia best practices
- Review common pitfalls
- Demonstrate new patterns
---
## Verification Checklist
- [ ] **All components work correctly**
- [ ] **All tests pass**
- [ ] **No console errors or warnings**
- [ ] **DevTools shows all stores**
- [ ] **HMR works in development**
- [ ] **SSR hydration works (if applicable)**
- [ ] **Production build succeeds**
- [ ] **No Vuex dependencies remain**
---
## Common Migration Gotchas
### ❌ Don't destructure without storeToRefs()
```typescript
// ❌ Wrong
const { user } = useAuthStore()
// ✅ Correct
const { user } = storeToRefs(useAuthStore())
```
### ❌ Don't call useStore() at module level
```typescript
// ❌ Wrong
const auth = useAuthStore()
router.beforeEach(() => { ... })
// ✅ Correct
router.beforeEach(() => {
const auth = useAuthStore()
})
```
### ❌ Don't forget to return all state in setup stores
```typescript
// ❌ Wrong
export const useStore = defineStore('store', () => {
const secret = ref('private') // Not returned!
return {}
})
// ✅ Correct
export const useStore = defineStore('store', () => {
const secret = ref('private')
return { secret } // Exposed
})
```
---
## Migration Timeline Example
**Week 1:**
- [ ] Set up Pinia alongside Vuex
- [ ] Migrate 1-2 simple modules
- [ ] Update related components
- [ ] Test thoroughly
**Week 2:**
- [ ] Migrate 3-4 more modules
- [ ] Update all related components
- [ ] Migrate router guards
- [ ] Update tests
**Week 3:**
- [ ] Migrate remaining modules
- [ ] Complete component updates
- [ ] Migrate plugins
- [ ] Final testing
**Week 4:**
- [ ] Remove Vuex entirely
- [ ] Final verification
- [ ] Deploy to production
- [ ] Monitor for issues
---
**Completed**: [ ] Migration fully complete and verified
**Notes:**
- Take your time with each module
- Test thoroughly at each step
- Keep Vuex and Pinia coexisting during migration
- Roll back quickly if issues arise
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 |