devskill 2.0.2

package/skills/vue-router-best-practices/reference/router-navigation-guard-infinite-loop.md

@@ -0,0 +1,187 @@
+---
+title: Navigation Guard Infinite Redirect Loops
+impact: HIGH
+impactDescription: Misconfigured navigation guards can trap users in infinite redirect loops, crashing the browser or making the app unusable
+type: gotcha
+tags: [vue3, vue-router, navigation-guards, redirect, debugging]
+---
+
+# Navigation Guard Infinite Redirect Loops
+
+**Impact: HIGH** - A common mistake in navigation guards is creating conditions that cause infinite redirects. Vue Router will detect this and show a warning, but in production, it can crash the browser or create a broken user experience.
+
+## Task Checklist
+
+- [ ] Always check if already on target route before redirecting
+- [ ] Test guard logic with all possible navigation scenarios
+- [ ] Add route meta to control which routes need protection
+- [ ] Use Vue Router devtools to debug redirect chains
+
+## The Problem
+
+```javascript
+// WRONG: Infinite loop - always redirects to login, even when on login!
+router.beforeEach((to, from) => {
+  if (!isAuthenticated()) {
+    return '/login'  // Redirects to /login, which triggers guard again...
+  }
+})
+
+// WRONG: Circular redirect between two routes
+router.beforeEach((to, from) => {
+  if (to.path === '/dashboard' && !hasProfile()) {
+    return '/profile'
+  }
+  if (to.path === '/profile' && !isVerified()) {
+    return '/dashboard'  // Back to dashboard, which goes to profile...
+  }
+})
+```
+
+**Error you'll see:**
+```
+[Vue Router warn]: Detected an infinite redirection in a navigation guard when going from "/" to "/login". Aborting to avoid a Stack Overflow.
+```
+
+## Solution 1: Exclude Target Route
+
+```javascript
+// CORRECT: Don't redirect if already going to login
+router.beforeEach((to, from) => {
+  if (!isAuthenticated() && to.path !== '/login') {
+    return '/login'
+  }
+})
+
+// CORRECT: Use route name for cleaner check
+router.beforeEach((to, from) => {
+  const publicPages = ['Login', 'Register', 'ForgotPassword']
+
+  if (!isAuthenticated() && !publicPages.includes(to.name)) {
+    return { name: 'Login' }
+  }
+})
+```
+
+## Solution 2: Use Route Meta Fields
+
+```javascript
+// router.js
+const routes = [
+  {
+    path: '/login',
+    name: 'Login',
+    component: Login,
+    meta: { requiresAuth: false }
+  },
+  {
+    path: '/dashboard',
+    name: 'Dashboard',
+    component: Dashboard,
+    meta: { requiresAuth: true }
+  },
+  {
+    path: '/public',
+    name: 'PublicPage',
+    component: PublicPage,
+    meta: { requiresAuth: false }
+  }
+]
+
+// Guard checks meta field
+router.beforeEach((to, from) => {
+  // Only redirect if route requires auth
+  if (to.meta.requiresAuth && !isAuthenticated()) {
+    return { name: 'Login', query: { redirect: to.fullPath } }
+  }
+})
+```
+
+## Solution 3: Handle Redirect Chains Carefully
+
+```javascript
+// CORRECT: Break potential circular redirects
+router.beforeEach((to, from) => {
+  // Prevent redirect loops by tracking redirect depth
+  const redirectCount = to.query._redirectCount || 0
+
+  if (redirectCount > 3) {
+    console.error('Too many redirects, stopping at:', to.path)
+    return '/error'  // Escape hatch
+  }
+
+  if (needsRedirect(to)) {
+    return {
+      path: getRedirectTarget(to),
+      query: { ...to.query, _redirectCount: redirectCount + 1 }
+    }
+  }
+})
+```
+
+## Solution 4: Centralized Redirect Logic
+
+```javascript
+// guards/auth.js
+export function createAuthGuard(router) {
+  const publicRoutes = new Set(['Login', 'Register', 'ForgotPassword', 'ResetPassword'])
+  const guestOnlyRoutes = new Set(['Login', 'Register'])
+
+  router.beforeEach((to, from) => {
+    const isPublic = publicRoutes.has(to.name)
+    const isGuestOnly = guestOnlyRoutes.has(to.name)
+    const isLoggedIn = isAuthenticated()
+
+    // Not logged in, trying to access protected route
+    if (!isLoggedIn && !isPublic) {
+      return { name: 'Login', query: { redirect: to.fullPath } }
+    }
+
+    // Logged in, trying to access guest-only route (like login page)
+    if (isLoggedIn && isGuestOnly) {
+      return { name: 'Dashboard' }
+    }
+
+    // All other cases: proceed
+  })
+}
+```
+
+## Debugging Redirect Loops
+
+```javascript
+// Add logging to understand the redirect chain
+router.beforeEach((to, from) => {
+  console.log(`Navigation: ${from.path} -> ${to.path}`)
+  console.log('Auth state:', isAuthenticated())
+  console.log('Route meta:', to.meta)
+
+  // Your guard logic here
+})
+
+// Or use afterEach for confirmed navigations
+router.afterEach((to, from) => {
+  console.log(`Navigated: ${from.path} -> ${to.path}`)
+})
+```
+
+## Common Redirect Loop Patterns
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| Auth check without exclusion | Login redirects to login | Exclude `/login` from check |
+| Role-based with circular deps | Admin -> User -> Admin | Use single source of truth for role requirements |
+| Onboarding flow | Step 1 -> Step 2 -> Step 1 | Track completion state properly |
+| Redirect query handling | Reading redirect creates new redirect | Process redirect only once |
+
+## Key Points
+
+1. **Always exclude the target route** - Never redirect to a route that would trigger the same redirect
+2. **Use route meta fields** - Cleaner than path string comparisons
+3. **Test edge cases** - Direct URL access, refresh, back button
+4. **Add logging during development** - Helps trace redirect chains
+5. **Have an escape hatch** - Error page or max redirect count
+
+## Reference
+- [Vue Router Navigation Guards](https://router.vuejs.org/guide/advanced/navigation-guards.html)
+- [Vue Router Route Meta Fields](https://router.vuejs.org/guide/advanced/meta.html)

package/skills/vue-router-best-practices/reference/router-navigation-guard-next-deprecated.md

@@ -0,0 +1,150 @@
+---
+title: Vue Router Navigation Guard next() Function Deprecated
+impact: HIGH
+impactDescription: Using the deprecated next() function incorrectly causes navigation to hang, infinite loops, or silent failures
+type: gotcha
+tags: [vue3, vue-router, navigation-guards, migration, async]
+---
+
+# Vue Router Navigation Guard next() Function Deprecated
+
+**Impact: HIGH** - The third `next()` argument in navigation guards is deprecated in Vue Router 4. While still supported for backward compatibility, using it incorrectly is one of the most common sources of bugs: calling it multiple times, forgetting to call it, or calling it conditionally without proper logic.
+
+## Task Checklist
+
+- [ ] Refactor guards to use return-based syntax instead of next()
+- [ ] Remove all next() calls from navigation guards
+- [ ] Use async/await pattern for asynchronous checks
+- [ ] Return false to cancel, return route to redirect, return nothing to proceed
+
+## The Problem
+
+```javascript
+// WRONG: Using deprecated next() function
+router.beforeEach((to, from, next) => {
+  if (!isAuthenticated) {
+    next('/login')  // Easy to forget this call
+  }
+  // BUG: next() not called when authenticated - navigation hangs!
+})
+
+// WRONG: Multiple next() calls
+router.beforeEach((to, from, next) => {
+  if (!isAuthenticated) {
+    next('/login')
+  }
+  next()  // BUG: Called twice when not authenticated!
+})
+
+// WRONG: next() in async code without proper handling
+router.beforeEach(async (to, from, next) => {
+  const user = await fetchUser()
+  if (!user) {
+    next('/login')
+  }
+  next()  // Still gets called even after redirect!
+})
+```
+
+## Solution: Use Return-Based Guards
+
+```javascript
+// CORRECT: Return-based syntax (modern Vue Router 4+)
+router.beforeEach((to, from) => {
+  if (!isAuthenticated) {
+    return '/login'  // Redirect
+  }
+  // Return nothing (undefined) to proceed
+})
+
+// CORRECT: Return false to cancel navigation
+router.beforeEach((to, from) => {
+  if (hasUnsavedChanges) {
+    return false  // Cancel navigation
+  }
+})
+
+// CORRECT: Async with return-based syntax
+router.beforeEach(async (to, from) => {
+  const user = await fetchUser()
+  if (!user) {
+    return { name: 'Login', query: { redirect: to.fullPath } }
+  }
+  // Proceed with navigation
+})
+```
+
+## Return Values Explained
+
+```javascript
+router.beforeEach((to, from) => {
+  // Return nothing/undefined - allow navigation
+  return
+
+  // Return false - cancel navigation, stay on current route
+  return false
+
+  // Return string path - redirect to path
+  return '/login'
+
+  // Return route object - redirect with full control
+  return { name: 'Login', query: { redirect: to.fullPath } }
+
+  // Return Error - cancel and trigger router.onError()
+  return new Error('Navigation cancelled')
+})
+```
+
+## If You Must Use next() (Legacy Code)
+
+If maintaining legacy code that uses `next()`, follow these rules strictly:
+
+```javascript
+// CORRECT: Exactly one next() call per code path
+router.beforeEach((to, from, next) => {
+  if (!isAuthenticated) {
+    next('/login')
+    return  // CRITICAL: Exit after calling next()
+  }
+
+  if (!hasPermission(to)) {
+    next('/forbidden')
+    return  // CRITICAL: Exit after calling next()
+  }
+
+  next()  // Only reached if all checks pass
+})
+```
+
+## Error Handling Pattern
+
+```javascript
+router.beforeEach(async (to, from) => {
+  try {
+    await validateAccess(to)
+    // Proceed
+  } catch (error) {
+    if (error.status === 401) {
+      return '/login'
+    }
+    if (error.status === 403) {
+      return '/forbidden'
+    }
+    // Log error and proceed anyway (or return false)
+    console.error('Access validation failed:', error)
+    return false
+  }
+})
+```
+
+## Key Points
+
+1. **Prefer return-based syntax** - Cleaner, less error-prone, modern standard
+2. **next() must be called exactly once** - If using legacy syntax, ensure single call per path
+3. **Always return/exit after redirect** - Prevent multiple navigation actions
+4. **Async guards work naturally** - Just return the redirect route or nothing
+5. **Test all code paths** - Each branch must result in either return or next()
+
+## Reference
+- [Vue Router Navigation Guards](https://router.vuejs.org/guide/advanced/navigation-guards.html)
+- [RFC: Remove next() from Navigation Guards](https://github.com/vuejs/rfcs/discussions/302)

package/skills/vue-router-best-practices/reference/router-param-change-no-lifecycle.md

@@ -0,0 +1,181 @@
+---
+title: Route Param Changes Do Not Trigger Lifecycle Hooks
+impact: HIGH
+impactDescription: Navigating between routes with different params reuses the component instance, skipping created/mounted hooks and leaving stale data
+type: gotcha
+tags: [vue3, vue-router, lifecycle, params, reactivity]
+---
+
+# Route Param Changes Do Not Trigger Lifecycle Hooks
+
+**Impact: HIGH** - When navigating between routes that use the same component (e.g., `/users/1` to `/users/2`), Vue Router reuses the existing component instance for performance. This means `onMounted`, `created`, and other lifecycle hooks do NOT fire, leaving you with stale data from the previous route.
+
+## Task Checklist
+
+- [ ] Use `watch` on route params for data fetching
+- [ ] Or use `onBeforeRouteUpdate` in-component guard
+- [ ] Or use `:key="route.params.id"` to force re-creation (less efficient)
+- [ ] Never rely solely on `onMounted` for route-param-dependent data
+
+## The Problem
+
+```vue
+<!-- UserProfile.vue - Used for /users/:id -->
+<script setup>
+import { ref, onMounted } from 'vue'
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+const user = ref(null)
+
+// BUG: Only runs once when component first mounts!
+// Navigating from /users/1 to /users/2 does NOT trigger this
+onMounted(async () => {
+  user.value = await fetchUser(route.params.id)
+})
+</script>
+
+<template>
+  <div>
+    <!-- Still shows User 1 data when navigating to /users/2! -->
+    <h1>{{ user?.name }}</h1>
+  </div>
+</template>
+```
+
+**Scenario:**
+1. Visit `/users/1` - Component mounts, fetches User 1 data
+2. Navigate to `/users/2` - Component is REUSED, onMounted doesn't run
+3. UI still shows User 1's data!
+
+## Solution 1: Watch Route Params (Recommended)
+
+```vue
+<script setup>
+import { ref, watch } from 'vue'
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+const user = ref(null)
+const loading = ref(false)
+
+// Watch for param changes - handles both initial load and navigation
+watch(
+  () => route.params.id,
+  async (newId) => {
+    loading.value = true
+    user.value = await fetchUser(newId)
+    loading.value = false
+  },
+  { immediate: true }  // Run immediately for initial load
+)
+</script>
+```
+
+## Solution 2: Use onBeforeRouteUpdate Guard
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+import { useRoute, onBeforeRouteUpdate } from 'vue-router'
+
+const route = useRoute()
+const user = ref(null)
+
+async function loadUser(id) {
+  user.value = await fetchUser(id)
+}
+
+// Initial load
+onMounted(() => loadUser(route.params.id))
+
+// Handle param changes within same route
+onBeforeRouteUpdate(async (to, from) => {
+  if (to.params.id !== from.params.id) {
+    await loadUser(to.params.id)
+  }
+})
+</script>
+```
+
+## Solution 3: Force Component Re-creation with Key
+
+```vue
+<!-- App.vue or parent component -->
+<template>
+  <router-view :key="$route.fullPath" />
+</template>
+```
+
+**Tradeoffs:**
+- Simple but less performant
+- Destroys and recreates component on every param change
+- Loses component state
+- Use only when component state should reset completely
+
+## Solution 4: Composable for Route-Reactive Data
+
+```javascript
+// composables/useRouteData.js
+import { ref, watch } from 'vue'
+import { useRoute } from 'vue-router'
+
+export function useRouteData(paramName, fetcher) {
+  const route = useRoute()
+  const data = ref(null)
+  const loading = ref(false)
+  const error = ref(null)
+
+  watch(
+    () => route.params[paramName],
+    async (id) => {
+      if (!id) return
+
+      loading.value = true
+      error.value = null
+
+      try {
+        data.value = await fetcher(id)
+      } catch (e) {
+        error.value = e
+      } finally {
+        loading.value = false
+      }
+    },
+    { immediate: true }
+  )
+
+  return { data, loading, error }
+}
+```
+
+```vue
+<!-- Usage in component -->
+<script setup>
+import { useRouteData } from '@/composables/useRouteData'
+import { fetchUser } from '@/api/users'
+
+const { data: user, loading, error } = useRouteData('id', fetchUser)
+</script>
+```
+
+## What Triggers vs. What Doesn't
+
+| Navigation Type | Lifecycle Hooks | beforeRouteUpdate | Watch on params |
+|----------------|-----------------|-------------------|-----------------|
+| `/users/1` to `/posts/1` | YES | NO | YES |
+| `/users/1` to `/users/2` | NO | YES | YES |
+| `/users/1?tab=a` to `/users/1?tab=b` | NO | YES | NO (different watch) |
+| `/users/1` to `/users/1` (same) | NO | NO | NO |
+
+## Key Points
+
+1. **Same route, different params = same component instance** - This is a performance optimization
+2. **Lifecycle hooks only fire once** - When component first mounts
+3. **Use `watch` with `immediate: true`** - Covers both initial load and updates
+4. **`onBeforeRouteUpdate` is navigation-aware** - Good for data that must load before view updates
+5. **`:key="route.fullPath"` is a sledgehammer** - Use only when necessary
+
+## Reference
+- [Vue Router Dynamic Route Matching](https://router.vuejs.org/guide/essentials/dynamic-matching.html#reacting-to-params-changes)
+- [Vue School: Reacting to Param Changes](https://vueschool.io/lessons/reacting-to-param-changes)