devskill 2.0.2

package/skills/vue-pinia-best-practices/reference/state-url-for-ephemeral-filters.md

@@ -0,0 +1,238 @@
+---
+title: Use URL State for Shareable Filters Instead of Stores
+impact: MEDIUM
+impactDescription: Storing filter/search state only in stores loses state on refresh and prevents link sharing
+type: best-practice
+tags: [vue3, state-management, url, router, filters, ux, vue-router]
+---
+
+# Use URL State for Shareable Filters Instead of Stores
+
+**Impact: MEDIUM** - Storing ephemeral UI state like filters, search queries, pagination, and sorting only in Pinia or component state means users lose that state on page refresh and cannot share links to specific filtered views. This hurts user experience and SEO.
+
+For state that represents a "view" of data, use URL query parameters instead of or alongside stores.
+
+## Task Checklist
+
+- [ ] Identify ephemeral UI state: filters, search, sort, pagination, tab selection
+- [ ] Store such state in URL query parameters
+- [ ] Sync URL state with component/store state bidirectionally
+- [ ] Consider using VueUse's `useRouteQuery` for type-safe URL state
+- [ ] Keep URL state minimal and human-readable
+
+## The Problem: Store-Only State
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useProductStore } from '@/stores/products'
+
+const productStore = useProductStore()
+
+// Filter state in component/store only
+const selectedCategory = ref('all')
+const priceRange = ref([0, 1000])
+const sortBy = ref('newest')
+const searchQuery = ref('')
+
+// Problems with this approach:
+// 1. User refreshes page → filters reset to defaults
+// 2. User bookmarks page → bookmark doesn't include filter state
+// 3. User shares link → friend sees unfiltered view
+// 4. Back button doesn't restore previous filter state
+</script>
+```
+
+## The Solution: URL-Based State
+
+```vue
+<script setup>
+import { computed, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+const route = useRoute()
+const router = useRouter()
+
+// Read filter state FROM URL
+const selectedCategory = computed({
+  get: () => route.query.category || 'all',
+  set: (value) => updateQuery({ category: value === 'all' ? undefined : value })
+})
+
+const sortBy = computed({
+  get: () => route.query.sort || 'newest',
+  set: (value) => updateQuery({ sort: value === 'newest' ? undefined : value })
+})
+
+const searchQuery = computed({
+  get: () => route.query.q || '',
+  set: (value) => updateQuery({ q: value || undefined })
+})
+
+const page = computed({
+  get: () => parseInt(route.query.page) || 1,
+  set: (value) => updateQuery({ page: value === 1 ? undefined : value })
+})
+
+// Helper to update URL without full navigation
+function updateQuery(newParams) {
+  router.push({
+    query: {
+      ...route.query,
+      ...newParams
+    }
+  })
+}
+</script>
+
+<template>
+  <div>
+    <input v-model="searchQuery" placeholder="Search...">
+
+    <select v-model="selectedCategory">
+      <option value="all">All Categories</option>
+      <option value="electronics">Electronics</option>
+      <option value="clothing">Clothing</option>
+    </select>
+
+    <select v-model="sortBy">
+      <option value="newest">Newest</option>
+      <option value="price-low">Price: Low to High</option>
+      <option value="price-high">Price: High to Low</option>
+    </select>
+
+    <!-- URL now looks like: /products?category=electronics&sort=price-low&q=phone -->
+    <!-- Users can bookmark, share, and refresh without losing state -->
+  </div>
+</template>
+```
+
+## Using VueUse for Cleaner Code
+
+VueUse provides `useRouteQuery` for type-safe URL state:
+
+```vue
+<script setup>
+import { useRouteQuery } from '@vueuse/router'
+
+// Automatically syncs with URL query parameters
+const category = useRouteQuery('category', 'all')
+const sort = useRouteQuery('sort', 'newest')
+const search = useRouteQuery('q', '')
+const page = useRouteQuery('page', 1, { transform: Number })
+const showOutOfStock = useRouteQuery('inStock', false, { transform: Boolean })
+
+// Arrays work too
+const selectedTags = useRouteQuery('tags', [], {
+  transform: (v) => Array.isArray(v) ? v : v ? [v] : []
+})
+</script>
+
+<template>
+  <input v-model="search" placeholder="Search...">
+  <select v-model="category">...</select>
+  <input type="checkbox" v-model="showOutOfStock"> Show out of stock
+</template>
+```
+
+## Hybrid Approach: URL + Store
+
+For complex state, sync URL with store:
+
+```javascript
+// stores/productFilters.js
+import { defineStore } from 'pinia'
+import { useRoute, useRouter } from 'vue-router'
+import { watch } from 'vue'
+
+export const useProductFiltersStore = defineStore('productFilters', () => {
+  const route = useRoute()
+  const router = useRouter()
+
+  // Local reactive state
+  const category = ref('all')
+  const sortBy = ref('newest')
+  const searchQuery = ref('')
+  const page = ref(1)
+
+  // Initialize from URL on store creation
+  function initFromUrl() {
+    category.value = route.query.category || 'all'
+    sortBy.value = route.query.sort || 'newest'
+    searchQuery.value = route.query.q || ''
+    page.value = parseInt(route.query.page) || 1
+  }
+
+  // Sync state changes TO URL
+  function syncToUrl() {
+    router.replace({
+      query: {
+        category: category.value !== 'all' ? category.value : undefined,
+        sort: sortBy.value !== 'newest' ? sortBy.value : undefined,
+        q: searchQuery.value || undefined,
+        page: page.value > 1 ? page.value : undefined
+      }
+    })
+  }
+
+  // Watch for URL changes (back/forward navigation)
+  watch(() => route.query, initFromUrl, { immediate: true })
+
+  // Watch for state changes and sync to URL
+  watch([category, sortBy, searchQuery, page], syncToUrl)
+
+  return {
+    category,
+    sortBy,
+    searchQuery,
+    page,
+    initFromUrl
+  }
+})
+```
+
+## What Goes in URL vs Store
+
+| State Type | URL | Store | Notes |
+|------------|-----|-------|-------|
+| Filters | Yes | Optional | Shareable, bookmarkable |
+| Search query | Yes | Optional | SEO benefit |
+| Pagination | Yes | Optional | Deep linking |
+| Sort order | Yes | Optional | User expectation |
+| Selected tab | Yes | Optional | Deep linking |
+| Modal open state | Maybe | Yes | Usually not shareable |
+| Form draft | No | Yes | Private, temporary |
+| User session | No | Yes | Security |
+| Shopping cart | No | Yes | Persistence needed |
+
+## Benefits of URL State
+
+1. **Shareable**: Users can share exact filtered views
+2. **Bookmarkable**: Save specific searches/filters
+3. **Browser history**: Back/forward works as expected
+4. **SEO**: Search engines can index filtered pages
+5. **Refresh-safe**: State survives page reload
+6. **Deep linking**: Direct links to specific states
+
+## Clean URL Best Practices
+
+```javascript
+// GOOD: Clean, readable URLs
+/products?category=electronics&sort=price&q=phone
+
+// AVOID: Overly complex URLs
+/products?filters=%7B%22category%22%3A%22electronics%22%7D
+```
+
+```javascript
+// Use defaults to keep URLs minimal
+const sort = useRouteQuery('sort', 'newest')
+
+// URL shows: /products (when using default sort)
+// URL shows: /products?sort=price-low (when changed)
+```
+
+## Reference
+- [VueUse - useRouteQuery](https://vueuse.org/router/useRouteQuery/)
+- [Vue Router - Query Parameters](https://router.vuejs.org/guide/essentials/passing-props.html#passing-props-to-route-components)
+- [Mastering Pinia - URL State](https://masteringpinia.com/blog/top-5-mistakes-to-avoid-when-using-pinia)

package/skills/vue-pinia-best-practices/reference/state-use-pinia-for-large-apps.md

@@ -0,0 +1,262 @@
+---
+title: Use Pinia for Large-Scale Vue Applications
+impact: MEDIUM
+impactDescription: Hand-rolled reactive stores lack DevTools integration, TypeScript support, and debugging capabilities needed for production apps
+type: best-practice
+tags: [vue3, pinia, state-management, devtools, architecture, scalability]
+---
+
+# Use Pinia for Large-Scale Vue Applications
+
+**Impact: MEDIUM** - While Vue's Composition API allows creating simple reactive stores with `reactive()` and `ref()`, these hand-rolled solutions lack the tooling, conventions, and debugging capabilities needed for large-scale production applications. Pinia is the official Vue state management solution and should be used for any non-trivial application.
+
+## Task Checklist
+
+- [ ] Use Pinia for applications with shared state across multiple components
+- [ ] Use Pinia when team collaboration requires consistent patterns
+- [ ] Use Pinia when you need Vue DevTools state debugging
+- [ ] Hand-rolled `reactive()` is acceptable only for simple, single-developer apps
+- [ ] Migrate from Vuex to Pinia (Vuex is in maintenance mode)
+
+## When Hand-Rolled State is Acceptable
+
+Simple reactive state is fine for:
+- Prototypes and proof-of-concepts
+- Very small applications with minimal shared state
+- Single-developer projects with limited scope
+- Learning purposes
+
+```javascript
+// Simple hand-rolled store - OK for small apps
+import { reactive, readonly } from 'vue'
+
+export const store = reactive({
+  count: 0,
+  increment() {
+    this.count++
+  }
+})
+```
+
+## When to Use Pinia
+
+Use Pinia when you have any of these requirements:
+
+### 1. DevTools Integration
+
+Pinia provides rich Vue DevTools support:
+- Timeline of state changes
+- State inspection and editing
+- Time-travel debugging
+- Action tracking
+
+```javascript
+// Pinia store - fully visible in DevTools
+import { defineStore } from 'pinia'
+
+export const useCounterStore = defineStore('counter', {
+  state: () => ({ count: 0 }),
+  actions: {
+    increment() {
+      this.count++  // Tracked in DevTools timeline
+    }
+  }
+})
+```
+
+### 2. TypeScript Support
+
+Pinia has excellent TypeScript inference:
+
+```typescript
+// Full type inference without extra configuration
+import { defineStore } from 'pinia'
+
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    name: '',
+    age: 0,
+    preferences: {
+      theme: 'light' as 'light' | 'dark'
+    }
+  }),
+
+  getters: {
+    // Return type is inferred
+    displayName: (state) => state.name || 'Anonymous'
+  },
+
+  actions: {
+    // Full parameter type checking
+    setUser(name: string, age: number) {
+      this.name = name
+      this.age = age
+    }
+  }
+})
+
+// Usage is fully typed
+const userStore = useUserStore()
+userStore.name  // string
+userStore.displayName  // string
+userStore.setUser('John', 30)  // Type-checked
+```
+
+### 3. Team Collaboration
+
+Pinia enforces conventions that help teams:
+
+```javascript
+// Consistent structure across all stores
+// stores/products.js
+export const useProductsStore = defineStore('products', {
+  state: () => ({ /* ... */ }),
+  getters: { /* ... */ },
+  actions: { /* ... */ }
+})
+
+// stores/cart.js - Same structure
+export const useCartStore = defineStore('cart', {
+  state: () => ({ /* ... */ }),
+  getters: { /* ... */ },
+  actions: { /* ... */ }
+})
+```
+
+### 4. Hot Module Replacement (HMR)
+
+Pinia supports HMR out of the box - state persists during development:
+
+```javascript
+// State survives code changes during development
+// No need to re-login or re-create state after every edit
+```
+
+### 5. Server-Side Rendering (SSR)
+
+Pinia handles SSR state correctly:
+
+```javascript
+// Automatic per-request state isolation
+// State serialization for hydration
+// No cross-request pollution
+```
+
+### 6. Plugin Ecosystem
+
+Pinia supports plugins for common needs:
+
+```javascript
+import { createPinia } from 'pinia'
+import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
+
+const pinia = createPinia()
+pinia.use(piniaPluginPersistedstate)
+
+// Now stores can persist to localStorage
+export const useSettingsStore = defineStore('settings', {
+  state: () => ({
+    theme: 'light',
+    language: 'en'
+  }),
+  persist: true  // Automatically saved/restored
+})
+```
+
+## Pinia vs Hand-Rolled Comparison
+
+| Feature | Hand-Rolled `reactive()` | Pinia |
+|---------|-------------------------|-------|
+| DevTools integration | No | Yes |
+| TypeScript inference | Manual | Automatic |
+| HMR support | No | Yes |
+| SSR support | Manual | Built-in |
+| Plugins | No | Yes |
+| Time-travel debugging | No | Yes |
+| Learning curve | Lower | Slightly higher |
+| Bundle size | Smaller | ~1KB |
+| Team conventions | None | Enforced |
+
+## Migration from Vuex
+
+Vuex is now in maintenance mode. Migrate to Pinia for new features:
+
+```javascript
+// Vuex (legacy)
+export default createStore({
+  state: { count: 0 },
+  mutations: {
+    INCREMENT(state) { state.count++ }
+  },
+  actions: {
+    increment({ commit }) { commit('INCREMENT') }
+  }
+})
+
+// Pinia (recommended)
+export const useCounterStore = defineStore('counter', {
+  state: () => ({ count: 0 }),
+  actions: {
+    increment() { this.count++ }  // No mutations needed!
+  }
+})
+```
+
+**Pinia advantages over Vuex:**
+- No mutations (simpler mental model)
+- Better TypeScript support
+- No nested modules complexity
+- Smaller bundle size
+- Composition API style available
+
+## Pinia Store Styles
+
+Choose the style that fits your team:
+
+### Options Style (Similar to Options API)
+
+```javascript
+export const useCounterStore = defineStore('counter', {
+  state: () => ({ count: 0 }),
+  getters: {
+    double: (state) => state.count * 2
+  },
+  actions: {
+    increment() { this.count++ }
+  }
+})
+```
+
+### Setup Style (Composition API)
+
+```javascript
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0)
+  const double = computed(() => count.value * 2)
+  function increment() { count.value++ }
+
+  return { count, double, increment }
+})
+```
+
+## Quick Start
+
+```bash
+npm install pinia
+```
+
+```javascript
+// main.js
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(createPinia())
+app.mount('#app')
+```
+
+## Reference
+- [Vue.js - State Management](https://vuejs.org/guide/scaling-up/state-management.html)
+- [Pinia Documentation](https://pinia.vuejs.org/)
+- [Pinia vs Vuex](https://pinia.vuejs.org/introduction.html#comparison-with-vuex)

package/skills/vue-pinia-best-practices/reference/store-method-binding-parentheses.md

@@ -0,0 +1,191 @@
+---
+title: Include Parentheses When Calling Store Methods in Templates
+impact: MEDIUM
+impactDescription: Omitting parentheses on store method calls loses the correct 'this' context, causing unexpected behavior
+type: gotcha
+tags: [vue3, state-management, reactive, methods, templates, this-binding]
+---
+
+# Include Parentheses When Calling Store Methods in Templates
+
+**Impact: MEDIUM** - When calling methods on a reactive store object in Vue templates, you must include parentheses (even without arguments) to ensure the method is called with the correct `this` context. Without parentheses, `this` inside the method may not refer to the store.
+
+This is a subtle gotcha that can cause hard-to-debug issues with hand-rolled reactive stores.
+
+## Task Checklist
+
+- [ ] Always use parentheses when calling store methods in templates: `@click="store.increment()"`
+- [ ] Avoid passing store methods as bare references: `@click="store.increment"` is problematic
+- [ ] Consider using arrow functions or Pinia (which handles this automatically)
+- [ ] Test store method calls work correctly with `this` references
+
+## The Problem
+
+```javascript
+// store.js
+import { reactive } from 'vue'
+
+export const store = reactive({
+  count: 0,
+  increment() {
+    this.count++  // 'this' should refer to the store
+  }
+})
+```
+
+```vue
+<template>
+  <!-- WRONG: Without parentheses, 'this' binding may be lost -->
+  <button @click="store.increment">
+    {{ store.count }}
+  </button>
+</template>
+```
+
+When you write `@click="store.increment"` (without parentheses), Vue passes the method as a callback to the event handler. The method gets called without being bound to the store object, so `this` inside `increment()` may be `undefined` or the global object instead of the store.
+
+## The Solution
+
+```vue
+<template>
+  <!-- CORRECT: With parentheses, method is called with correct context -->
+  <button @click="store.increment()">
+    {{ store.count }}
+  </button>
+</template>
+```
+
+With parentheses, you're telling Vue to call `store.increment()` directly, which preserves the `this` context as the store object.
+
+## Why This Happens
+
+In JavaScript, when you reference a method without calling it, you get the function itself without its binding:
+
+```javascript
+const store = {
+  count: 0,
+  increment() {
+    this.count++
+  }
+}
+
+// With parentheses - correct context
+store.increment()  // this === store ✓
+
+// Without parentheses - getting the function
+const fn = store.increment
+fn()  // this === undefined (in strict mode) ✗
+```
+
+Vue's event handler behavior:
+- `@click="store.increment"` - Vue receives `store.increment` as a function and calls it later
+- `@click="store.increment()"` - Vue evaluates `store.increment()` when the event fires
+
+## Alternative Solutions
+
+### 1. Use Arrow Functions in the Template
+
+```vue
+<template>
+  <button @click="() => store.increment()">
+    {{ store.count }}
+  </button>
+</template>
+```
+
+### 2. Bind Methods in the Store Definition
+
+```javascript
+// store.js
+import { reactive } from 'vue'
+
+const state = reactive({
+  count: 0
+})
+
+// Methods defined separately, arrow functions don't have 'this' issues
+export const store = {
+  get count() { return state.count },
+  increment: () => { state.count++ }
+}
+```
+
+### 3. Use Pinia (Recommended)
+
+Pinia handles method binding correctly:
+
+```javascript
+// stores/counter.js
+import { defineStore } from 'pinia'
+
+export const useCounterStore = defineStore('counter', {
+  state: () => ({ count: 0 }),
+  actions: {
+    increment() {
+      this.count++  // Pinia ensures 'this' is correct
+    }
+  }
+})
+```
+
+```vue
+<script setup>
+import { useCounterStore } from '@/stores/counter'
+const counter = useCounterStore()
+</script>
+
+<template>
+  <!-- Both work correctly with Pinia -->
+  <button @click="counter.increment">Works</button>
+  <button @click="counter.increment()">Also works</button>
+</template>
+```
+
+### 4. Wrap in a Local Function
+
+```vue
+<script setup>
+import { store } from './store'
+
+// Wrap store method to ensure correct binding
+function increment() {
+  store.increment()
+}
+</script>
+
+<template>
+  <!-- Now safe to use without parentheses -->
+  <button @click="increment">
+    {{ store.count }}
+  </button>
+</template>
+```
+
+## When This Matters
+
+This gotcha specifically affects:
+- Hand-rolled reactive stores using `reactive()`
+- Methods that reference `this` inside them
+- Direct method references in templates without parentheses
+
+It does NOT affect:
+- Pinia stores (methods are auto-bound)
+- Arrow function methods (no `this` binding)
+- Methods that don't use `this`
+- Method calls with parentheses
+
+## Quick Reference
+
+| Pattern | Safe? | Notes |
+|---------|-------|-------|
+| `@click="store.method()"` | Yes | Explicit call preserves context |
+| `@click="store.method"` | No* | Context may be lost |
+| `@click="() => store.method()"` | Yes | Arrow wrapper preserves context |
+| `@click="localMethod"` | Yes | Component methods are auto-bound |
+| Pinia: `@click="store.action"` | Yes | Pinia handles binding |
+
+*Only problematic if the method uses `this`
+
+## Reference
+- [Vue.js State Management - Tip on Method Binding](https://vuejs.org/guide/scaling-up/state-management.html#simple-state-management-with-reactivity-api)
+- [MDN - this in JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this)

package/skills/vue-router-best-practices/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hyf0, SerKo <https://github.com/serkodev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.