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/plugins-composables.md
View on GitHub# Pinia Plugins and Composables Guide
Complete guide for extending Pinia with plugins and integrating Vue composables into stores.
**Last Updated**: 2025-11-21
---
## Plugins
### Creating a Plugin
```typescript
export function myPlugin(context) {
context.pinia // Pinia instance
context.app // Vue app instance (createApp)
context.store // Store being augmented
context.options // Store definition options
// Return object to add properties to every store
return {
secret: 'the cake is a lie'
}
}
// Register
const pinia = createPinia()
pinia.use(myPlugin)
```
### Adding State via Plugins
```typescript
import { ref } from 'vue'
pinia.use(({ store }) => {
const secret = ref('my-secret')
// Add to both store and $state for SSR
store.secret = secret
store.$state.secret = secret
return { secret }
})
```
### Adding Options via Plugins
```typescript
// Define custom store option
defineStore('search', {
// Custom option
debounce: {
search: 300,
reset: 100
},
actions: {
search() { /* ... */ },
reset() { /* ... */ }
}
})
// Plugin reads and implements
import { debounce } from 'lodash'
pinia.use(({ options, store }) => {
if (options.debounce) {
return Object.keys(options.debounce).reduce((debouncedActions, action) => {
debouncedActions[action] = debounce(
store[action],
options.debounce[action]
)
return debouncedActions
}, {})
}
})
```
### TypeScript Plugin Typing
```typescript
import 'pinia'
declare module 'pinia' {
export interface PiniaCustomProperties {
// Add custom store properties
router: Router
}
export interface PiniaCustomStateProperties<S> {
// Add custom state properties
myCustomState: string
}
export interface DefineStoreOptionsBase<S, Store> {
// Add custom store options
debounce?: Partial<Record<keyof StoreActions<Store>, number>>
}
}
```
---
## Using Composables in Stores
### Option Stores
Call composables in `state()`:
```typescript
import { useLocalStorage } from '@vueuse/core'
export const useStore = defineStore('store', {
state: () => ({
// ✅ Works - returns writable ref
theme: useLocalStorage('theme', 'dark')
})
})
```
**Limitations:**
- Can only return writable state (`ref()`)
- Cannot use composables that return functions or readonly data
### Setup Stores
Almost any composable works:
```typescript
import { useMediaControls } from '@vueuse/core'
export const useVideoStore = defineStore('video', () => {
const videoEl = ref<HTMLVideoElement>()
// ✅ All properties auto-categorized
const { playing, volume, currentTime, togglePictureInPicture } =
useMediaControls(videoEl, { src: '/video.mp4' })
return {
playing,
volume,
currentTime,
togglePictureInPicture,
videoEl
}
})
```
**SSR Handling:**
```typescript
import { skipHydrate } from 'pinia'
return {
// Don't hydrate this from SSR state
videoEl: skipHydrate(videoEl)
}
```
---
## Common Plugin Patterns
### Pattern 1: LocalStorage Persistence Plugin
```typescript
import { PiniaPluginContext } from 'pinia'
export function persistPlugin({ store }: PiniaPluginContext) {
// Restore state from localStorage
const stored = localStorage.getItem(store.$id)
if (stored) {
store.$patch(JSON.parse(stored))
}
// Save state to localStorage on every change
store.$subscribe((mutation, state) => {
localStorage.setItem(store.$id, JSON.stringify(state))
})
}
// Register
const pinia = createPinia()
pinia.use(persistPlugin)
```
**When to use**: Persisting user preferences, cart data, etc.
### Pattern 2: Router Integration Plugin
```typescript
import { Router } from 'vue-router'
export function routerPlugin(router: Router) {
return ({ store }: PiniaPluginContext) => {
store.router = router
}
}
// Register
const pinia = createPinia()
pinia.use(routerPlugin(router))
// Now all stores have access to router
export const useStore = defineStore('store', {
actions: {
navigateHome() {
this.router.push('/')
}
}
})
```
### Pattern 3: Debounce Plugin
```typescript
import { debounce } from 'lodash'
pinia.use(({ options, store }) => {
if (options.debounce) {
return Object.keys(options.debounce).reduce((debouncedActions, action) => {
debouncedActions[action] = debounce(
store[action],
options.debounce[action]
)
return debouncedActions
}, {})
}
})
// Usage
export const useSearchStore = defineStore('search', {
debounce: {
search: 300 // 300ms debounce
},
actions: {
search(query: string) {
// This will be debounced
}
}
})
```
### Pattern 4: Logger Plugin
```typescript
pinia.use(({ store }) => {
store.$onAction(({ name, args, after, onError }) => {
const startTime = Date.now()
console.log(`[Action] ${store.$id}.${name}`, args)
after((result) => {
console.log(`[Success] ${store.$id}.${name} (${Date.now() - startTime}ms)`, result)
})
onError((error) => {
console.error(`[Error] ${store.$id}.${name}`, error)
})
})
})
```
### Pattern 5: API Client Plugin
```typescript
export function apiPlugin(apiClient: ApiClient) {
return ({ store }: PiniaPluginContext) => {
store.$api = apiClient
}
}
// Register
const pinia = createPinia()
pinia.use(apiPlugin(myApiClient))
// Usage
export const useUserStore = defineStore('user', {
actions: {
async fetchUsers() {
this.users = await this.$api.get('/users')
}
}
})
```
---
## VueUse Composables Integration
### useLocalStorage Example
```typescript
import { useLocalStorage } from '@vueuse/core'
export const useSettingsStore = defineStore('settings', () => {
// Automatically synced with localStorage
const theme = useLocalStorage('theme', 'dark')
const language = useLocalStorage('language', 'en')
function toggleTheme() {
theme.value = theme.value === 'dark' ? 'light' : 'dark'
}
return { theme, language, toggleTheme }
})
```
### useMediaQuery Example
```typescript
import { useMediaQuery } from '@vueuse/core'
export const useLayoutStore = defineStore('layout', () => {
const isMobile = useMediaQuery('(max-width: 768px)')
const isTablet = useMediaQuery('(min-width: 769px) and (max-width: 1024px)')
const isDesktop = useMediaQuery('(min-width: 1025px)')
return { isMobile, isTablet, isDesktop }
})
```
### useFetch Example
```typescript
import { useFetch } from '@vueuse/core'
export const useDataStore = defineStore('data', () => {
const { data, error, isFetching, execute } = useFetch('/api/data').json()
return { data, error, isFetching, execute }
})
```
### useWebSocket Example
```typescript
import { useWebSocket } from '@vueuse/core'
export const useChatStore = defineStore('chat', () => {
const { status, data, send, open, close } = useWebSocket('ws://localhost:3000')
const messages = ref<string[]>([])
watch(data, (newMessage) => {
if (newMessage) {
messages.value.push(newMessage)
}
})
function sendMessage(text: string) {
send(text)
}
return { status, messages, sendMessage, open, close }
})
```
---
## Advanced Plugin Patterns
### Conditional Plugin Application
```typescript
pinia.use(({ store, options }) => {
// Only apply to stores with specific option
if (options.persist) {
// Implement persistence
}
})
// Usage
export const useStore = defineStore('store', {
persist: true, // Enable persistence for this store
state: () => ({ count: 0 })
})
```
### Plugin with Cleanup
```typescript
pinia.use(({ store }) => {
const interval = setInterval(() => {
store.$state.timestamp = Date.now()
}, 1000)
// Cleanup when store is disposed
store.$dispose(() => {
clearInterval(interval)
})
})
```
### Cross-Store Plugin
```typescript
pinia.use(({ store }) => {
if (store.$id === 'auth') {
// Watch auth state changes
watch(() => store.isAuthenticated, (isAuth) => {
if (!isAuth) {
// Clear all other stores when user logs out
const allStores = pinia._s // Access all stores
allStores.forEach((s) => {
if (s.$id !== 'auth' && s.$reset) {
s.$reset()
}
})
}
})
}
})
```
---
## Composables Best Practices
### DO:
- ✅ Use setup stores for composables integration
- ✅ Return all composable outputs for SSR
- ✅ Use `skipHydrate()` for browser-only refs (DOM elements)
- ✅ Handle composable errors gracefully
- ✅ Document composable dependencies
### DON'T:
- ❌ Use composables returning functions in option stores' `state()`
- ❌ Forget to return composable values from setup stores
- ❌ Mix composables with complex computed logic (keep simple)
- ❌ Ignore SSR compatibility of composables
- ❌ Use DOM-dependent composables without SSR guards
---
## Plugin TypeScript Examples
### Strong Typing for Custom Properties
```typescript
// types.ts
import 'pinia'
import { Router } from 'vue-router'
import { ApiClient } from './api'
declare module 'pinia' {
export interface PiniaCustomProperties {
router: Router
$api: ApiClient
}
}
// Now all stores have typed access
export const useStore = defineStore('store', {
actions: {
navigate() {
this.router.push('/') // ✅ Fully typed
},
async fetchData() {
const data = await this.$api.get('/data') // ✅ Fully typed
}
}
})
```
### Custom State Properties
```typescript
declare module 'pinia' {
export interface PiniaCustomStateProperties<S> {
createdAt: number
updatedAt: number
}
}
// Plugin implementation
pinia.use(({ store }) => {
store.$state.createdAt = Date.now()
store.$state.updatedAt = Date.now()
store.$subscribe(() => {
store.$state.updatedAt = Date.now()
})
})
```
---
**See also:**
- `ssr-and-nuxt.md` for SSR-safe composables usage
- `testing-guide.md` for testing plugins
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 |