devskill 2.0.2

package/skills/vue-pinia-best-practices/reference/pinia-no-active-pinia-error.md

@@ -0,0 +1,248 @@
+---
+title: Fix "No Active Pinia" Error - Store Setup Timing
+impact: HIGH
+impactDescription: Using Pinia stores before app.use(pinia) causes "getActivePinia was called but there was no active Pinia" error
+type: gotcha
+tags: [vue3, pinia, state-management, setup, initialization, error]
+---
+
+# Fix "No Active Pinia" Error - Store Setup Timing
+
+**Impact: HIGH** - The error "getActivePinia() was called but there was no active Pinia" is one of the most common Pinia errors. It occurs when you try to use a store before Pinia has been installed on the Vue app, causing your application to crash.
+
+## Task Checklist
+
+- [ ] Ensure `app.use(pinia)` is called before `app.mount()`
+- [ ] Ensure `app.use(pinia)` is called before `app.use(router)` if router guards use stores
+- [ ] Never call `useXxxStore()` in module-level (top-level) code
+- [ ] Only call `useXxxStore()` inside setup functions, composables, or after app initialization
+- [ ] Check for `<script setup>` vs `<script>` - the latter runs too early
+
+## The Error
+
+```
+[🍍]: "getActivePinia()" was called but there was no active Pinia.
+Did you forget to install pinia?
+```
+
+## Common Cause 1: Wrong Plugin Order
+
+```javascript
+// main.js - WRONG ORDER
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import router from './router'  // Router uses a store in navigation guard
+import App from './App.vue'
+
+const app = createApp(App)
+
+// WRONG: Router is installed first, but its guards use stores
+app.use(router)  // Router guard calls useAuthStore() - FAILS!
+app.use(createPinia())
+app.mount('#app')
+```
+
+**Fix: Install Pinia first:**
+
+```javascript
+// main.js - CORRECT ORDER
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import router from './router'
+import App from './App.vue'
+
+const app = createApp(App)
+
+// CORRECT: Pinia installed before anything that uses stores
+app.use(createPinia())
+app.use(router)  // Now router guards can safely use stores
+app.mount('#app')
+```
+
+## Common Cause 2: Store Used at Module Level
+
+```javascript
+// api.js - WRONG: Module-level store usage
+import { useAuthStore } from '@/stores/auth'
+
+// This runs immediately when the module is imported!
+const authStore = useAuthStore()  // ERROR: No active Pinia yet
+
+export function fetchUser() {
+  return fetch('/api/user', {
+    headers: {
+      Authorization: `Bearer ${authStore.token}`
+    }
+  })
+}
+```
+
+**Fix: Call useStore inside functions:**
+
+```javascript
+// api.js - CORRECT: Store used inside function
+import { useAuthStore } from '@/stores/auth'
+
+export function fetchUser() {
+  // Store is accessed when function is called, not when module loads
+  const authStore = useAuthStore()
+
+  return fetch('/api/user', {
+    headers: {
+      Authorization: `Bearer ${authStore.token}`
+    }
+  })
+}
+```
+
+## Common Cause 3: Script Tag Missing "setup"
+
+```vue
+<!-- WRONG: <script> runs before component setup -->
+<script>
+import { useUserStore } from '@/stores/user'
+
+// This runs too early, before the component is set up
+const userStore = useUserStore()  // ERROR!
+
+export default {
+  // ...
+}
+</script>
+```
+
+**Fix: Use `<script setup>` or move to setup function:**
+
+```vue
+<!-- CORRECT: <script setup> runs at the right time -->
+<script setup>
+import { useUserStore } from '@/stores/user'
+
+// This runs during component setup, Pinia is active
+const userStore = useUserStore()  // Works!
+</script>
+```
+
+```vue
+<!-- CORRECT: Options API with setup function -->
+<script>
+import { useUserStore } from '@/stores/user'
+
+export default {
+  setup() {
+    // Called during component initialization
+    const userStore = useUserStore()  // Works!
+    return { userStore }
+  }
+}
+</script>
+```
+
+## Common Cause 4: mapStores with Parentheses
+
+```vue
+<script>
+import { mapStores } from 'pinia'
+import { useProductsStore } from '@/stores/products'
+
+export default {
+  computed: {
+    // WRONG: Called the function instead of passing it
+    ...mapStores(useProductsStore())  // ERROR!
+  }
+}
+</script>
+```
+
+**Fix: Pass the function reference, not the result:**
+
+```vue
+<script>
+import { mapStores } from 'pinia'
+import { useProductsStore } from '@/stores/products'
+
+export default {
+  computed: {
+    // CORRECT: Pass the function without calling it
+    ...mapStores(useProductsStore)  // No parentheses!
+  }
+}
+</script>
+```
+
+## Common Cause 5: Router Guards Before Pinia
+
+```javascript
+// router/index.js - WRONG
+import { createRouter } from 'vue-router'
+import { useAuthStore } from '@/stores/auth'
+
+const router = createRouter({ /* ... */ })
+
+// This guard is registered immediately
+router.beforeEach((to) => {
+  // When this runs during app startup, Pinia might not be ready
+  const authStore = useAuthStore()  // May fail!
+
+  if (to.meta.requiresAuth && !authStore.isLoggedIn) {
+    return '/login'
+  }
+})
+```
+
+**Fix: Use lazy store access or ensure plugin order:**
+
+```javascript
+// router/index.js - CORRECT
+import { createRouter } from 'vue-router'
+
+const router = createRouter({ /* ... */ })
+
+router.beforeEach((to) => {
+  // Dynamically import to avoid module-level execution
+  const { useAuthStore } = await import('@/stores/auth')
+  const authStore = useAuthStore()
+
+  if (to.meta.requiresAuth && !authStore.isLoggedIn) {
+    return '/login'
+  }
+})
+
+// OR ensure main.js has correct order:
+// app.use(pinia)
+// app.use(router)
+```
+
+## Debugging Checklist
+
+When you see "No active Pinia":
+
+1. **Check main.js order**: Is `app.use(pinia)` before other plugins?
+2. **Search for top-level useStore calls**: Any store usage outside functions/setup?
+3. **Check script tags**: Using `<script>` instead of `<script setup>`?
+4. **Check mapStores usage**: Using `useStore()` instead of `useStore`?
+5. **Check import chains**: Does an early import trigger store usage?
+
+## Safe Pattern: Conditional Store Access
+
+```javascript
+// For code that might run before Pinia is ready
+import { getActivePinia } from 'pinia'
+
+export function safelyUseStore() {
+  const pinia = getActivePinia()
+
+  if (!pinia) {
+    console.warn('Pinia not initialized yet')
+    return null
+  }
+
+  const { useUserStore } = await import('@/stores/user')
+  return useUserStore()
+}
+```
+
+## Reference
+- [Vue Land FAQ - No Active Pinia](https://vue-land.github.io/faq/no-active-pinia)
+- [Pinia - Using a Store Outside of a Component](https://pinia.vuejs.org/core-concepts/outside-component-usage.html)
+- [Pinia - Getting Started](https://pinia.vuejs.org/getting-started.html)

package/skills/vue-pinia-best-practices/reference/pinia-setup-store-return-all-state.md

@@ -0,0 +1,227 @@
+---
+title: Return All State Properties in Pinia Setup Stores
+impact: HIGH
+impactDescription: Not returning state properties in setup stores breaks SSR, DevTools, and plugin compatibility
+type: gotcha
+tags: [vue3, pinia, state-management, setup-stores, ssr, devtools]
+---
+
+# Return All State Properties in Pinia Setup Stores
+
+**Impact: HIGH** - When using Pinia's setup store syntax (Composition API style), you MUST return all state properties from the setup function. Private state that isn't returned will break Server-Side Rendering (SSR), Vue DevTools inspection, and Pinia plugins.
+
+This is a critical gotcha that can cause silent failures in production.
+
+## Task Checklist
+
+- [ ] Return ALL reactive state properties from setup stores
+- [ ] Do not create "private" state by omitting it from the return
+- [ ] If you need private state, use a prefix convention instead (e.g., `_internal`)
+- [ ] Test stores with DevTools to verify all state is visible
+- [ ] Verify SSR hydration includes all necessary state
+
+## The Problem: Private State in Setup Stores
+
+```javascript
+// stores/user.js - WRONG: Private state breaks SSR/DevTools
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+
+export const useUserStore = defineStore('user', () => {
+  // Public state
+  const name = ref('')
+  const email = ref('')
+
+  // "Private" state - NOT returned
+  const authToken = ref('')  // Won't be serialized for SSR!
+  const lastFetchTime = ref(null)  // Won't appear in DevTools!
+
+  const isLoggedIn = computed(() => !!authToken.value)
+
+  async function login(credentials) {
+    const response = await fetch('/api/login', {
+      method: 'POST',
+      body: JSON.stringify(credentials)
+    })
+    const data = await response.json()
+
+    authToken.value = data.token  // This state won't transfer to client in SSR!
+    name.value = data.name
+    email.value = data.email
+    lastFetchTime.value = Date.now()
+  }
+
+  // WRONG: Not returning authToken and lastFetchTime
+  return {
+    name,
+    email,
+    isLoggedIn,
+    login
+  }
+})
+```
+
+**What breaks:**
+
+1. **SSR Hydration**: `authToken` and `lastFetchTime` won't be serialized and sent to the client
+2. **DevTools**: These properties won't appear in the store inspector
+3. **Plugins**: Persistence plugins won't save these properties
+4. **Time-travel debugging**: Can't track changes to hidden state
+
+## The Solution: Return Everything
+
+```javascript
+// stores/user.js - CORRECT: All state returned
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+
+export const useUserStore = defineStore('user', () => {
+  // All state properties
+  const name = ref('')
+  const email = ref('')
+  const authToken = ref('')
+  const lastFetchTime = ref(null)
+
+  // Getters
+  const isLoggedIn = computed(() => !!authToken.value)
+
+  // Actions
+  async function login(credentials) {
+    const response = await fetch('/api/login', {
+      method: 'POST',
+      body: JSON.stringify(credentials)
+    })
+    const data = await response.json()
+
+    authToken.value = data.token
+    name.value = data.name
+    email.value = data.email
+    lastFetchTime.value = Date.now()
+  }
+
+  function logout() {
+    authToken.value = ''
+    name.value = ''
+    email.value = ''
+  }
+
+  // CORRECT: Return ALL state, getters, and actions
+  return {
+    // State
+    name,
+    email,
+    authToken,
+    lastFetchTime,
+    // Getters
+    isLoggedIn,
+    // Actions
+    login,
+    logout
+  }
+})
+```
+
+## If You Need "Private" State
+
+Use naming conventions instead of actually hiding state:
+
+```javascript
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+
+export const useUserStore = defineStore('user', () => {
+  // Convention: underscore prefix for "internal" state
+  // Still returned, but signals it's not for external use
+  const _authToken = ref('')
+  const _lastFetchTime = ref(null)
+
+  // Public state
+  const name = ref('')
+  const email = ref('')
+
+  const isLoggedIn = computed(() => !!_authToken.value)
+
+  // Return everything - convention communicates intent
+  return {
+    // "Private" - use with caution
+    _authToken,
+    _lastFetchTime,
+    // Public
+    name,
+    email,
+    isLoggedIn
+  }
+})
+```
+
+## Option Stores Don't Have This Problem
+
+With the Options API syntax, all state is automatically tracked:
+
+```javascript
+// stores/user.js - Options syntax: all state is tracked automatically
+import { defineStore } from 'pinia'
+
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    name: '',
+    email: '',
+    authToken: '',  // Automatically included
+    lastFetchTime: null  // Automatically included
+  }),
+
+  getters: {
+    isLoggedIn: (state) => !!state.authToken
+  },
+
+  actions: {
+    async login(credentials) {
+      // ...
+    }
+  }
+})
+```
+
+## How Setup Stores Map to State
+
+Understanding the mapping helps avoid mistakes:
+
+```javascript
+defineStore('example', () => {
+  // ref() becomes state
+  const count = ref(0)  // → state.count
+
+  // computed() becomes getters
+  const double = computed(() => count.value * 2)  // → getters.double
+
+  // Regular functions become actions
+  function increment() {  // → actions.increment
+    count.value++
+  }
+
+  // CRITICAL: Must return all of them
+  return { count, double, increment }
+})
+```
+
+## Debugging: Verify All State is Returned
+
+```javascript
+// Test that DevTools can see all state
+import { useUserStore } from '@/stores/user'
+
+const userStore = useUserStore()
+
+// In DevTools console or tests:
+console.log(userStore.$state)
+// Should include ALL reactive state properties
+
+// Check what's returned
+console.log(Object.keys(userStore))
+// Should include: name, email, authToken, lastFetchTime, isLoggedIn, login, logout
+```
+
+## Reference
+- [Pinia - Setup Stores](https://pinia.vuejs.org/core-concepts/#setup-stores)
+- [Pinia - SSR](https://pinia.vuejs.org/ssr/)
+- [Mastering Pinia - Common Mistakes](https://masteringpinia.com/blog/top-5-mistakes-to-avoid-when-using-pinia)

package/skills/vue-pinia-best-practices/reference/pinia-store-destructuring-breaks-reactivity.md

@@ -0,0 +1,193 @@
+---
+title: Use storeToRefs When Destructuring Pinia Stores
+impact: HIGH
+impactDescription: Destructuring Pinia stores directly breaks reactivity - state changes won't trigger UI updates
+type: gotcha
+tags: [vue3, pinia, state-management, reactivity, destructuring]
+---
+
+# Use storeToRefs When Destructuring Pinia Stores
+
+**Impact: HIGH** - Pinia stores are wrapped with `reactive`, so destructuring them directly extracts non-reactive values. Changes to the store won't be reflected in your component, causing stale UI and confusing bugs.
+
+This is one of the most common mistakes when using Pinia, especially for developers coming from Vuex or other state management libraries.
+
+## Task Checklist
+
+- [ ] Never destructure state or getters directly from a Pinia store
+- [ ] Use `storeToRefs()` to extract reactive state and getters
+- [ ] Destructure actions directly (they don't need reactivity)
+- [ ] Remember: `storeToRefs` is for state/getters, direct destructure is for actions
+
+## The Problem: Direct Destructuring
+
+```vue
+<script setup>
+import { useUserStore } from '@/stores/user'
+
+const userStore = useUserStore()
+
+// WRONG: Direct destructuring breaks reactivity
+const { name, email, isLoggedIn } = userStore
+
+// Later, when store updates...
+userStore.login({ name: 'John', email: 'john@example.com' })
+
+// name and email are still the OLD values!
+// UI won't update because these are no longer reactive
+console.log(name) // undefined (or initial value)
+</script>
+
+<template>
+  <!-- This won't update when store changes -->
+  <div>{{ name }}</div>
+</template>
+```
+
+## The Solution: Use storeToRefs
+
+```vue
+<script setup>
+import { storeToRefs } from 'pinia'
+import { useUserStore } from '@/stores/user'
+
+const userStore = useUserStore()
+
+// CORRECT: Use storeToRefs for state and getters
+const { name, email, isLoggedIn } = storeToRefs(userStore)
+
+// Actions can be destructured directly (they're just functions)
+const { login, logout } = userStore
+
+// Now when the store updates...
+login({ name: 'John', email: 'john@example.com' })
+
+// name and email are reactive refs that update automatically
+console.log(name.value) // 'John'
+</script>
+
+<template>
+  <!-- This updates reactively -->
+  <div>{{ name }}</div>
+  <button @click="logout">Logout</button>
+</template>
+```
+
+## Understanding Why This Happens
+
+Pinia stores are reactive objects (like `reactive()`). When you destructure:
+
+```javascript
+const store = useCounterStore()
+// store is a reactive Proxy
+
+const { count } = store
+// count is now just a primitive number (0), not reactive
+// It's like doing: const count = 0
+
+// vs with storeToRefs
+const { count } = storeToRefs(store)
+// count is now a ref that stays connected to the store
+// It's like: const count = computed(() => store.count)
+```
+
+## Complete Pattern: State, Getters, and Actions
+
+```vue
+<script setup>
+import { storeToRefs } from 'pinia'
+import { useCartStore } from '@/stores/cart'
+
+const cartStore = useCartStore()
+
+// State and getters: USE storeToRefs
+const {
+  items,           // state
+  itemCount,       // getter
+  totalPrice,      // getter
+  isEmpty          // getter
+} = storeToRefs(cartStore)
+
+// Actions: destructure directly
+const {
+  addItem,
+  removeItem,
+  clearCart
+} = cartStore
+</script>
+
+<template>
+  <div v-if="isEmpty">Cart is empty</div>
+  <div v-else>
+    <p>{{ itemCount }} items - ${{ totalPrice }}</p>
+    <ul>
+      <li v-for="item in items" :key="item.id">
+        {{ item.name }}
+        <button @click="removeItem(item.id)">Remove</button>
+      </li>
+    </ul>
+    <button @click="clearCart">Clear All</button>
+  </div>
+</template>
+```
+
+## Alternative: Don't Destructure
+
+If you prefer, you can avoid destructuring entirely:
+
+```vue
+<script setup>
+import { useUserStore } from '@/stores/user'
+
+const userStore = useUserStore()
+// Use userStore.name, userStore.login(), etc. directly
+</script>
+
+<template>
+  <div>{{ userStore.name }}</div>
+  <button @click="userStore.logout()">Logout</button>
+</template>
+```
+
+This works fine but is more verbose for stores used frequently in the template.
+
+## Common Mistake: Mixing storeToRefs with Actions
+
+```vue
+<script setup>
+import { storeToRefs } from 'pinia'
+import { useUserStore } from '@/stores/user'
+
+const userStore = useUserStore()
+
+// WRONG: Don't include actions in storeToRefs
+// Actions are just functions and storeToRefs will skip them anyway
+const { name, login } = storeToRefs(userStore)
+// login is undefined! Actions aren't included in storeToRefs result
+
+// CORRECT: Separate state/getters from actions
+const { name } = storeToRefs(userStore)
+const { login } = userStore
+</script>
+```
+
+## TypeScript Tip
+
+With TypeScript, the types work correctly:
+
+```typescript
+import { storeToRefs } from 'pinia'
+import { useUserStore } from '@/stores/user'
+
+const userStore = useUserStore()
+
+// name is Ref<string>, email is Ref<string>
+const { name, email } = storeToRefs(userStore)
+
+// login is (credentials: Credentials) => Promise<void>
+const { login } = userStore
+```
+
+## Reference
+- [Pinia - Destructuring from a Store](https://pinia.vuejs.org/core-concepts/#destructuring-from-a-store)
+- [Pinia API - storeToRefs](https://pinia.vuejs.org/api/modules/pinia.html#storetorefs)