devskill 2.0.2

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

@@ -0,0 +1,23 @@
+---
+name: vue-router-best-practices
+description: "Vue Router 4 patterns, navigation guards, route params, and route-component lifecycle interactions."
+version: 1.0.0
+license: MIT
+author: github.com/vuejs-ai
+---
+
+Vue Router best practices, common gotchas, and navigation patterns.
+
+### Navigation Guards
+- Navigating between same route with different params → See [router-beforeenter-no-param-trigger](reference/router-beforeenter-no-param-trigger.md)
+- Accessing component instance in beforeRouteEnter guard → See [router-beforerouteenter-no-this](reference/router-beforerouteenter-no-this.md)
+- Navigation guard making API calls without awaiting → See [router-guard-async-await-pattern](reference/router-guard-async-await-pattern.md)
+- Users trapped in infinite redirect loops → See [router-navigation-guard-infinite-loop](reference/router-navigation-guard-infinite-loop.md)
+- Navigation guard using deprecated next() function → See [router-navigation-guard-next-deprecated](reference/router-navigation-guard-next-deprecated.md)
+
+### Route Lifecycle
+- Stale data when navigating between same route → See [router-param-change-no-lifecycle](reference/router-param-change-no-lifecycle.md)
+- Event listeners persisting after component unmounts → See [router-simple-routing-cleanup](reference/router-simple-routing-cleanup.md)
+
+### Setup
+- Building production single-page application → See [router-use-vue-router-for-production](reference/router-use-vue-router-for-production.md)

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

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/vuejs-ai/skills/vue-router-best-practices`
+- **Git SHA:** `f3dd1bf4d3ac78331bdc903e4519d561c538ca6a`
+- **Synced:** 2026-03-24

package/skills/vue-router-best-practices/reference/router-beforeenter-no-param-trigger.md

@@ -0,0 +1,167 @@
+---
+title: Per-Route beforeEnter Guards Ignore Param/Query Changes
+impact: MEDIUM
+impactDescription: Route-level beforeEnter guards don't fire when only params, query, or hash change, causing unexpected bypasses of validation logic
+type: gotcha
+tags: [vue3, vue-router, navigation-guards, params, query]
+---
+
+# Per-Route beforeEnter Guards Ignore Param/Query Changes
+
+**Impact: MEDIUM** - The `beforeEnter` guard defined in route configuration only triggers when entering a route from a DIFFERENT route. Changes to params, query strings, or hash within the same route do NOT trigger `beforeEnter`, potentially bypassing important validation logic.
+
+## Task Checklist
+
+- [ ] Use in-component `onBeforeRouteUpdate` for param/query changes
+- [ ] Or use global `beforeEach` with route.params/query checks
+- [ ] Document which guards protect which scenarios
+- [ ] Test navigation between same route with different params
+
+## The Problem
+
+```javascript
+// router.js
+const routes = [
+  {
+    path: '/orders/:id',
+    component: OrderDetail,
+    beforeEnter: async (to, from) => {
+      // This runs when entering from /products
+      // But NOT when navigating from /orders/1 to /orders/2!
+      const order = await checkOrderAccess(to.params.id)
+      if (!order.canView) {
+        return '/unauthorized'
+      }
+    }
+  }
+]
+```
+
+**Scenario:**
+1. User navigates from `/products` to `/orders/1` - beforeEnter runs, access checked
+2. User navigates from `/orders/1` to `/orders/2` - beforeEnter DOES NOT run!
+3. User might access order they don't have permission for!
+
+## What Triggers beforeEnter vs. What Doesn't
+
+| Navigation | beforeEnter fires? |
+|------------|-------------------|
+| `/products` → `/orders/1` | YES |
+| `/orders/1` → `/orders/2` | NO |
+| `/orders/1` → `/orders/1?tab=details` | NO |
+| `/orders/1#section` → `/orders/1#other` | NO |
+| `/orders/1` → `/products` → `/orders/2` | YES (leaving and re-entering) |
+
+## Solution 1: Add In-Component Guard
+
+```vue
+<!-- OrderDetail.vue -->
+<script setup>
+import { onBeforeRouteUpdate } from 'vue-router'
+
+// Handle param changes within the same route
+onBeforeRouteUpdate(async (to, from) => {
+  if (to.params.id !== from.params.id) {
+    const order = await checkOrderAccess(to.params.id)
+    if (!order.canView) {
+      return '/unauthorized'
+    }
+  }
+})
+</script>
+```
+
+## Solution 2: Use Global beforeEach Instead
+
+```javascript
+// router.js
+router.beforeEach(async (to, from) => {
+  // Handle all order access checks globally
+  if (to.name === 'OrderDetail') {
+    // This runs on EVERY navigation to this route, including param changes
+    const order = await checkOrderAccess(to.params.id)
+    if (!order.canView) {
+      return '/unauthorized'
+    }
+  }
+})
+```
+
+## Solution 3: Combine Both Guards
+
+```javascript
+// router.js - For entering from different route
+const routes = [
+  {
+    path: '/orders/:id',
+    component: OrderDetail,
+    beforeEnter: (to) => validateOrderAccess(to.params.id)
+  }
+]
+
+// In component - For param changes within route
+// OrderDetail.vue
+onBeforeRouteUpdate((to) => validateOrderAccess(to.params.id))
+
+// Shared validation function
+async function validateOrderAccess(orderId) {
+  const order = await checkOrderAccess(orderId)
+  if (!order.canView) {
+    return '/unauthorized'
+  }
+}
+```
+
+## Solution 4: Use beforeEnter with Array of Guards
+
+```javascript
+// guards/orderGuards.js
+export const orderAccessGuard = async (to) => {
+  const order = await checkOrderAccess(to.params.id)
+  if (!order.canView) {
+    return '/unauthorized'
+  }
+}
+
+// router.js
+const routes = [
+  {
+    path: '/orders/:id',
+    component: OrderDetail,
+    beforeEnter: [orderAccessGuard]  // Can add multiple guards
+  }
+]
+
+// Still need in-component guard for param changes!
+```
+
+## Full Navigation Guard Execution Order
+
+Understanding when each guard type fires:
+
+```
+1. beforeRouteLeave (in-component, leaving component)
+2. beforeEach (global)
+3. beforeEnter (per-route, ONLY when entering from different route)
+4. beforeRouteEnter (in-component, entering component)
+5. beforeResolve (global)
+6. afterEach (global, after navigation confirmed)
+
+For param/query changes on same route:
+1. beforeRouteUpdate (in-component) - ONLY this fires!
+2. beforeEach (global)
+3. beforeResolve (global)
+4. afterEach (global)
+```
+
+## Key Points
+
+1. **beforeEnter is for route ENTRY only** - Not for within-route changes
+2. **Use onBeforeRouteUpdate for param changes** - This is the in-component solution
+3. **Global beforeEach always runs** - Good for centralized validation
+4. **Test param change scenarios** - Easy to miss during development
+5. **Consider security implications** - Param-based access control needs both guards
+
+## Reference
+- [Vue Router Navigation Guards](https://router.vuejs.org/guide/advanced/navigation-guards.html)
+- [Vue Router Per-Route Guards](https://router.vuejs.org/guide/advanced/navigation-guards.html#per-route-guard)

package/skills/vue-router-best-practices/reference/router-beforerouteenter-no-this.md

@@ -0,0 +1,176 @@
+---
+title: beforeRouteEnter Cannot Access Component Instance
+impact: MEDIUM
+impactDescription: The beforeRouteEnter guard runs before component creation, so 'this' is undefined; use the next callback to access the instance
+type: gotcha
+tags: [vue3, vue-router, navigation-guards, lifecycle, this]
+---
+
+# beforeRouteEnter Cannot Access Component Instance
+
+**Impact: MEDIUM** - The `beforeRouteEnter` in-component navigation guard executes BEFORE the component is created, meaning you cannot access `this` or any component instance properties. This is the ONLY navigation guard that supports a callback in the `next()` function to access the component instance after navigation.
+
+## Task Checklist
+
+- [ ] Use next(vm => ...) callback to access component instance
+- [ ] Or use composition API guards which have different patterns
+- [ ] Move data fetching logic appropriately based on timing needs
+- [ ] Consider using global guards for data that doesn't need component access
+
+## The Problem
+
+```javascript
+// Options API - WRONG: this is undefined
+export default {
+  data() {
+    return { user: null }
+  },
+  beforeRouteEnter(to, from, next) {
+    // BUG: this is undefined here - component doesn't exist yet!
+    this.user = await fetchUser(to.params.id)  // ERROR!
+    next()
+  }
+}
+```
+
+## Solution: Use next() Callback (Options API)
+
+```javascript
+// Options API - CORRECT: Use callback to access vm
+export default {
+  data() {
+    return {
+      user: null,
+      loading: true
+    }
+  },
+
+  beforeRouteEnter(to, from, next) {
+    // Fetch data before component exists
+    fetchUser(to.params.id)
+      .then(user => {
+        // Pass callback to next() - receives component instance as 'vm'
+        next(vm => {
+          vm.user = user
+          vm.loading = false
+        })
+      })
+      .catch(error => {
+        next(vm => {
+          vm.error = error
+          vm.loading = false
+        })
+      })
+  }
+}
+```
+
+## Solution: Async beforeRouteEnter (Options API)
+
+```javascript
+export default {
+  data() {
+    return { userData: null }
+  },
+
+  async beforeRouteEnter(to, from, next) {
+    try {
+      const user = await fetchUser(to.params.id)
+
+      // Still need callback for component access
+      next(vm => {
+        vm.userData = user
+      })
+    } catch (error) {
+      // Redirect on error
+      next('/error')
+    }
+  }
+}
+```
+
+## Composition API Alternative
+
+In Composition API with `<script setup>`, you cannot use `beforeRouteEnter` directly because the component instance is being set up. Use different patterns instead:
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+import { useRoute, onBeforeRouteUpdate } from 'vue-router'
+
+const route = useRoute()
+const user = ref(null)
+const loading = ref(true)
+
+// Option 1: Fetch in onMounted (after component exists)
+onMounted(async () => {
+  user.value = await fetchUser(route.params.id)
+  loading.value = false
+})
+
+// Option 2: Handle subsequent param changes
+onBeforeRouteUpdate(async (to, from) => {
+  if (to.params.id !== from.params.id) {
+    loading.value = true
+    user.value = await fetchUser(to.params.id)
+    loading.value = false
+  }
+})
+</script>
+```
+
+## Route-Level Data Fetching
+
+For data that should load BEFORE navigation, use route-level guards:
+
+```javascript
+// router.js
+const routes = [
+  {
+    path: '/users/:id',
+    component: () => import('./UserProfile.vue'),
+    beforeEnter: async (to, from) => {
+      try {
+        // Store data for component to access
+        const user = await fetchUser(to.params.id)
+        to.meta.user = user  // Attach to route meta
+      } catch (error) {
+        return '/error'
+      }
+    }
+  }
+]
+```
+
+```vue
+<!-- UserProfile.vue -->
+<script setup>
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+// Access pre-fetched data from meta
+const user = route.meta.user
+</script>
+```
+
+## Comparison of Navigation Guards
+
+| Guard | Has `this`/component? | Can delay navigation? | Use case |
+|-------|----------------------|----------------------|----------|
+| beforeRouteEnter | NO (use next callback) | YES | Pre-fetch, redirect if data missing |
+| beforeRouteUpdate | YES | YES | React to param changes |
+| beforeRouteLeave | YES | YES | Unsaved changes warning |
+| Global beforeEach | NO | YES | Auth checks |
+| Route beforeEnter | NO | YES | Route-specific validation |
+
+## Key Points
+
+1. **beforeRouteEnter runs before component creation** - No access to `this`
+2. **Use next(vm => ...) callback** - Only way to access component instance
+3. **Composition API has limitations** - Use onMounted or global guards instead
+4. **Consider route meta for pre-fetched data** - Clean separation of concerns
+5. **beforeRouteUpdate and beforeRouteLeave have component access** - They run when component exists
+
+## Reference
+- [Vue Router In-Component Guards](https://router.vuejs.org/guide/advanced/navigation-guards.html#in-component-guards)
+- [Vue Router Navigation Resolution Flow](https://router.vuejs.org/guide/advanced/navigation-guards.html#the-full-navigation-resolution-flow)

package/skills/vue-router-best-practices/reference/router-guard-async-await-pattern.md

@@ -0,0 +1,227 @@
+---
+title: Async Navigation Guards Require Proper Promise Handling
+impact: MEDIUM
+impactDescription: Unawaited promises in guards cause navigation to complete before async checks finish, allowing unauthorized access or missing data
+type: gotcha
+tags: [vue3, vue-router, navigation-guards, async, promises]
+---
+
+# Async Navigation Guards Require Proper Promise Handling
+
+**Impact: MEDIUM** - Navigation guards that perform async operations (API calls, auth checks) must properly handle promises. If you don't await async operations or return the promise, navigation completes before your check finishes, potentially allowing unauthorized access or navigating with incomplete data.
+
+## Task Checklist
+
+- [ ] Use async/await in navigation guards
+- [ ] Return the promise if not using async/await
+- [ ] Add loading states for long async operations
+- [ ] Implement timeouts for slow API calls
+- [ ] Handle errors to prevent navigation hanging
+
+## The Problem
+
+```javascript
+// WRONG: Not awaiting - navigation proceeds immediately
+router.beforeEach((to, from) => {
+  if (to.meta.requiresAuth) {
+    checkAuth()  // This returns a Promise but we're not waiting!
+    // Navigation continues before checkAuth completes
+  }
+})
+
+// WRONG: Async function but forgot return
+router.beforeEach(async (to, from) => {
+  if (to.meta.requiresAuth) {
+    const isValid = await checkAuth()
+    if (!isValid) {
+      // This redirect might happen after navigation already completed!
+      return '/login'
+    }
+  }
+  // Missing return - implicitly returns undefined, allowing navigation
+})
+```
+
+## Solution: Proper Async/Await Pattern
+
+```javascript
+// CORRECT: Async function with proper returns
+router.beforeEach(async (to, from) => {
+  if (to.meta.requiresAuth) {
+    try {
+      const isAuthenticated = await checkAuth()
+
+      if (!isAuthenticated) {
+        return { name: 'Login', query: { redirect: to.fullPath } }
+      }
+    } catch (error) {
+      console.error('Auth check failed:', error)
+      return { name: 'Error', params: { message: 'Authentication failed' } }
+    }
+  }
+  // Explicitly return nothing to proceed
+  return true
+})
+```
+
+## Solution: Promise-Based Pattern (Alternative)
+
+```javascript
+// CORRECT: Return promise explicitly
+router.beforeEach((to, from) => {
+  if (to.meta.requiresAuth) {
+    return checkAuth()
+      .then(isAuthenticated => {
+        if (!isAuthenticated) {
+          return { name: 'Login' }
+        }
+      })
+      .catch(error => {
+        console.error('Auth check failed:', error)
+        return { name: 'Error' }
+      })
+  }
+})
+```
+
+## Loading State During Async Guards
+
+```javascript
+// app/composables/useNavigationLoading.js
+import { ref } from 'vue'
+
+const isNavigating = ref(false)
+
+export function useNavigationLoading() {
+  return { isNavigating }
+}
+
+export function setupNavigationLoading(router) {
+  router.beforeEach(() => {
+    isNavigating.value = true
+  })
+
+  router.afterEach(() => {
+    isNavigating.value = false
+  })
+
+  router.onError(() => {
+    isNavigating.value = false
+  })
+}
+```
+
+```vue
+<!-- App.vue -->
+<script setup>
+import { useNavigationLoading } from '@/composables/useNavigationLoading'
+
+const { isNavigating } = useNavigationLoading()
+</script>
+
+<template>
+  <LoadingBar v-if="isNavigating" />
+  <router-view />
+</template>
+```
+
+## Timeout Pattern for Slow APIs
+
+```javascript
+// CORRECT: Add timeout to prevent indefinite waiting
+function withTimeout(promise, ms = 5000) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Request timeout')), ms)
+    )
+  ])
+}
+
+router.beforeEach(async (to, from) => {
+  if (to.meta.requiresAuth) {
+    try {
+      const isValid = await withTimeout(checkAuth(), 5000)
+      if (!isValid) {
+        return '/login'
+      }
+    } catch (error) {
+      if (error.message === 'Request timeout') {
+        // Let user through but show warning
+        console.warn('Auth check timed out')
+      } else {
+        return '/login'
+      }
+    }
+  }
+})
+```
+
+## Multiple Async Checks
+
+```javascript
+// CORRECT: Run independent checks in parallel
+router.beforeEach(async (to, from) => {
+  if (to.meta.requiresAuth && to.meta.requiresSubscription) {
+    try {
+      const [isAuthenticated, hasSubscription] = await Promise.all([
+        checkAuth(),
+        checkSubscription()
+      ])
+
+      if (!isAuthenticated) {
+        return '/login'
+      }
+
+      if (!hasSubscription) {
+        return '/subscribe'
+      }
+    } catch (error) {
+      return '/error'
+    }
+  }
+})
+```
+
+## Error Handling Best Practices
+
+```javascript
+router.beforeEach(async (to, from) => {
+  try {
+    // Your async logic here
+    await performChecks(to)
+  } catch (error) {
+    // Always handle errors to prevent navigation from hanging
+
+    if (error.response?.status === 401) {
+      return '/login'
+    }
+
+    if (error.response?.status === 403) {
+      return '/forbidden'
+    }
+
+    if (error.code === 'NETWORK_ERROR') {
+      // Offline - maybe allow navigation but show warning
+      return true
+    }
+
+    // Unknown error - redirect to error page
+    console.error('Navigation guard error:', error)
+    return { name: 'Error', state: { error: error.message } }
+  }
+})
+```
+
+## Key Points
+
+1. **Always await async operations** - Otherwise navigation proceeds immediately
+2. **Return values matter** - Return route to redirect, false to cancel, true/undefined to proceed
+3. **Handle all error cases** - Uncaught errors can hang navigation
+4. **Add timeouts** - Slow APIs shouldn't block navigation indefinitely
+5. **Show loading state** - Users need feedback during async checks
+6. **Parallelize independent checks** - Use Promise.all for better performance
+
+## Reference
+- [Vue Router Navigation Guards](https://router.vuejs.org/guide/advanced/navigation-guards.html)
+- [Vue Router Navigation Failures](https://router.vuejs.org/guide/advanced/navigation-failures.html)