@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/async-component-error-handling.md

@@ -0,0 +1,115 @@
+# Async Component Error Handling
+
+## Rule
+
+Always configure error handling for async components using `errorComponent` and/or `onError` callback. Without proper error handling, failed component loads can leave the UI in an undefined state with no user feedback.
+
+## Why This Matters
+
+Network failures, timeouts, and server errors are common in production. Without error handling, users see blank spaces or broken UIs with no indication of what went wrong or how to recover.
+
+## Bad Code
+
+```vue
+<script setup>
+import { defineAsyncComponent } from 'vue'
+
+// No error handling - fails silently
+const AsyncWidget = defineAsyncComponent(() =>
+  import('./Widget.vue')
+)
+</script>
+```
+
+```vue
+<script setup>
+import { defineAsyncComponent } from 'vue'
+
+// isLoading never becomes false on error - infinite spinner
+const isLoading = ref(true)
+const Widget = defineAsyncComponent({
+  loader: () => import('./Widget.vue').finally(() => {
+    isLoading.value = false  // Only runs on success
+  })
+})
+</script>
+```
+
+## Good Code
+
+```vue
+<script setup>
+import { defineAsyncComponent } from 'vue'
+import LoadingSpinner from './LoadingSpinner.vue'
+import ErrorDisplay from './ErrorDisplay.vue'
+
+const AsyncWidget = defineAsyncComponent({
+  loader: () => import('./Widget.vue'),
+  loadingComponent: LoadingSpinner,
+  errorComponent: ErrorDisplay,
+  delay: 200,    // Prevent loading flicker
+  timeout: 10000 // Show error after 10 seconds
+})
+</script>
+```
+
+```vue
+<script setup>
+import { defineAsyncComponent } from 'vue'
+
+// With retry logic using onError
+const AsyncWidget = defineAsyncComponent({
+  loader: () => import('./Widget.vue'),
+  loadingComponent: LoadingSpinner,
+  errorComponent: ErrorDisplay,
+  onError(error, retry, fail, attempts) {
+    if (attempts <= 3) {
+      // Retry up to 3 times
+      retry()
+    } else {
+      // Give up and show error component
+      fail()
+    }
+  }
+})
+</script>
+```
+
+```vue
+<script setup>
+import { defineAsyncComponent } from 'vue'
+
+// Fallback component pattern - catch in loader
+const AsyncWidget = defineAsyncComponent(() =>
+  import('./Widget.vue').catch(() => import('./WidgetFallback.vue'))
+)
+</script>
+```
+
+## onError Callback Parameters
+
+The `onError` callback receives four arguments:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `error` | `Error` | The error that caused the load to fail |
+| `retry` | `Function` | Call to retry loading the component |
+| `fail` | `Function` | Call to give up and show errorComponent |
+| `attempts` | `number` | Number of load attempts so far |
+
+## Key Points
+
+1. Always provide an `errorComponent` for production applications
+2. Use `timeout` to prevent indefinite loading states
+3. Consider retry logic with `onError` for transient network issues
+4. The `delay` option (default 200ms) prevents loading flicker on fast networks
+5. Use the fallback pattern (`.catch()` in loader) when you want a seamless degradation
+
+## SSR Warning
+
+Using `onError` with SSR can cause issues in some configurations, potentially leading to infinite loading. Test thoroughly in SSR environments.
+
+## References
+
+- [Vue.js Async Components Documentation](https://vuejs.org/guide/components/async)
+- [Handling Async Components' loading errors](https://awad.dev/blog/handling-async-component-loading-errors/)

package/skills/vue-debug-guides/reference/async-component-keepalive-ref-issue.md

@@ -0,0 +1,112 @@
+# Async Components with keep-alive Ref Issues
+
+## Rule
+
+When using `<keep-alive>`, `<component>`, and `defineAsyncComponent` together, be aware that template refs can become undefined when the component is re-activated after being deactivated.
+
+## Why This Matters
+
+This is a known Vue issue where the ref binding works correctly on first activation but becomes undefined on subsequent activations. This can cause runtime errors when trying to access component methods or properties through refs.
+
+## Problem Scenario
+
+```vue
+<script setup>
+import { ref, defineAsyncComponent } from 'vue'
+
+const AsyncWidget = defineAsyncComponent(() =>
+  import('./Widget.vue')
+)
+
+const currentComponent = ref(AsyncWidget)
+const widgetRef = ref(null)
+
+function callWidgetMethod() {
+  // May be undefined after component reactivation!
+  widgetRef.value?.doSomething()
+}
+</script>
+
+<template>
+  <keep-alive>
+    <component :is="currentComponent" ref="widgetRef" />
+  </keep-alive>
+</template>
+```
+
+## Workarounds
+
+### Option 1: Use onActivated to re-establish ref access
+
+```vue
+<script setup>
+import { ref, defineAsyncComponent, onActivated, nextTick } from 'vue'
+
+const AsyncWidget = defineAsyncComponent(() =>
+  import('./Widget.vue')
+)
+
+const currentComponent = ref(AsyncWidget)
+const widgetRef = ref(null)
+
+// Use a computed or method that waits for ref to be available
+async function callWidgetMethod() {
+  await nextTick()
+  if (widgetRef.value) {
+    widgetRef.value.doSomething()
+  }
+}
+</script>
+```
+
+### Option 2: Avoid mixing all three patterns
+
+If possible, use one of these alternatives:
+
+```vue
+<!-- Option A: Don't use keep-alive with async components -->
+<template>
+  <component :is="currentComponent" ref="widgetRef" />
+</template>
+
+<!-- Option B: Use static component with keep-alive -->
+<script setup>
+import Widget from './Widget.vue'  // Regular import
+</script>
+<template>
+  <keep-alive>
+    <component :is="Widget" ref="widgetRef" />
+  </keep-alive>
+</template>
+```
+
+### Option 3: Use provide/inject instead of refs
+
+```vue
+<!-- Parent.vue -->
+<script setup>
+import { provide, ref } from 'vue'
+
+const sharedState = ref({ /* shared data */ })
+provide('widgetState', sharedState)
+</script>
+
+<!-- Widget.vue (async component) -->
+<script setup>
+import { inject } from 'vue'
+const widgetState = inject('widgetState')
+</script>
+```
+
+## Key Points
+
+1. This is a known issue when combining `<keep-alive>`, `<component :is>`, and `defineAsyncComponent`
+2. Refs may become undefined after component deactivation/reactivation
+3. Use `nextTick` and null checks when accessing refs
+4. Consider alternative patterns like provide/inject for cross-component communication
+5. Test thoroughly when using this combination
+
+## References
+
+- [Vue.js GitHub Discussion #11334](https://github.com/orgs/vuejs/discussions/11334)
+- [Vue.js Async Components Documentation](https://vuejs.org/guide/components/async)

package/skills/vue-debug-guides/reference/async-component-suspense-control.md

@@ -0,0 +1,84 @@
+---
+title: Suspense Overrides Async Component Loading and Error Options
+impact: MEDIUM
+impactDescription: Async component loading/error options are ignored under a parent Suspense, leading to missing spinners and error UIs
+type: gotcha
+tags: [vue3, suspense, async-components, loading, error-handling]
+---
+
+# Suspense Overrides Async Component Loading and Error Options
+
+**Impact: MEDIUM** - When an async component renders inside a parent `<Suspense>`, its `loadingComponent`, `errorComponent`, `delay`, and `timeout` options do not run. The parent Suspense controls loading and error UX instead.
+
+## Task Checklist
+
+- [ ] Confirm whether the async component is inside a `<Suspense>` boundary
+- [ ] Use `suspensible: false` when the component must manage its own loading/error UI
+- [ ] Or move loading/error UI to the parent `<Suspense>` fallback and an error boundary (`onErrorCaptured`)
+- [ ] Provide a retry path for failed loads
+
+**Incorrect:**
+```vue
+<script setup>
+import { defineAsyncComponent } from 'vue'
+
+const AsyncDashboard = defineAsyncComponent({
+  loader: () => import('./Dashboard.vue'),
+  loadingComponent: LoadingSpinner,
+  errorComponent: ErrorDisplay,
+  timeout: 3000
+})
+</script>
+
+<template>
+  <Suspense>
+    <AsyncDashboard />
+    <template #fallback>Loading...</template>
+  </Suspense>
+</template>
+```
+
+**Correct (component handles its own states):**
+```vue
+<script setup>
+import { defineAsyncComponent } from 'vue'
+
+const AsyncDashboard = defineAsyncComponent({
+  loader: () => import('./Dashboard.vue'),
+  loadingComponent: LoadingSpinner,
+  errorComponent: ErrorDisplay,
+  timeout: 3000,
+  suspensible: false
+})
+</script>
+
+<template>
+  <AsyncDashboard />
+</template>
+```
+
+**Correct (parent Suspense owns loading/error UI):**
+```vue
+<script setup>
+import { onErrorCaptured, ref } from 'vue'
+import AsyncDashboard from './AsyncDashboard.vue'
+
+const error = ref(null)
+
+onErrorCaptured((err) => {
+  error.value = err
+  return false
+})
+</script>
+
+<template>
+  <ErrorDisplay v-if="error" :error="error" />
+
+  <Suspense v-else>
+    <AsyncDashboard />
+    <template #fallback>
+      <LoadingSpinner />
+    </template>
+  </Suspense>
+</template>
+```

package/skills/vue-debug-guides/reference/async-component-vue-router.md

@@ -0,0 +1,109 @@
+# Do Not Use defineAsyncComponent with Vue Router
+
+## Rule
+
+Never use `defineAsyncComponent` when configuring Vue Router route components. Vue Router has its own lazy loading mechanism using dynamic imports directly.
+
+## Why This Matters
+
+Vue Router's lazy loading is specifically designed for route-level code splitting. Using `defineAsyncComponent` for routes adds unnecessary overhead and can cause unexpected behavior with navigation guards, loading states, and route transitions.
+
+## Bad Code
+
+```javascript
+import { defineAsyncComponent } from 'vue'
+import { createRouter, createWebHistory } from 'vue-router'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/dashboard',
+      // WRONG: Don't use defineAsyncComponent here
+      component: defineAsyncComponent(() =>
+        import('./views/Dashboard.vue')
+      )
+    },
+    {
+      path: '/profile',
+      // WRONG: This also won't work as expected
+      component: defineAsyncComponent({
+        loader: () => import('./views/Profile.vue'),
+        loadingComponent: LoadingSpinner
+      })
+    }
+  ]
+})
+```
+
+## Good Code
+
+```javascript
+import { createRouter, createWebHistory } from 'vue-router'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/dashboard',
+      // CORRECT: Use dynamic import directly
+      component: () => import('./views/Dashboard.vue')
+    },
+    {
+      path: '/profile',
+      // CORRECT: Simple arrow function with import
+      component: () => import('./views/Profile.vue')
+    }
+  ]
+})
+```
+
+## Handling Loading States with Vue Router
+
+For route-level loading states, use Vue Router's navigation guards or a global loading indicator:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useRouter } from 'vue-router'
+
+const router = useRouter()
+const isLoading = ref(false)
+
+router.beforeEach(() => {
+  isLoading.value = true
+})
+
+router.afterEach(() => {
+  isLoading.value = false
+})
+</script>
+
+<template>
+  <LoadingBar v-if="isLoading" />
+  <RouterView />
+</template>
+```
+
+## When to Use defineAsyncComponent
+
+Use `defineAsyncComponent` for:
+- Components loaded conditionally within a page
+- Heavy components that aren't always needed
+- Modal dialogs or panels that load on demand
+
+Use Vue Router's lazy loading for:
+- Route-level components (views/pages)
+- Any component configured in route definitions
+
+## Key Points
+
+1. Vue Router and `defineAsyncComponent` are separate lazy loading mechanisms
+2. Route components should use direct dynamic imports: `() => import('./View.vue')`
+3. Use navigation guards for route-level loading indicators
+4. `defineAsyncComponent` is for component-level lazy loading within pages
+
+## References
+
+- [Vue Router Lazy Loading Routes](https://router.vuejs.org/guide/advanced/lazy-loading.html)
+- [Vue.js Async Components Documentation](https://vuejs.org/guide/components/async)

package/skills/vue-debug-guides/reference/attrs-event-listener-merging.md

@@ -0,0 +1,205 @@
+# Fallthrough Event Listeners Are Additive
+
+## Rule
+
+When an event listener is passed to a component as a fallthrough attribute, it is added to the root element's existing listeners of the same type - both will trigger. This is different from props where values are replaced. Be aware that both the component's internal handler and the parent's handler will execute.
+
+## Why This Matters
+
+- Developers may expect event listeners to override like props
+- Both handlers execute, which can cause double submissions, duplicate API calls
+- Order of execution: internal handler first, then fallthrough handler
+- This is actually useful for composition but can cause bugs if unexpected
+
+## Bad Code
+
+```vue
+<!-- BaseButton.vue - Potential double-action bug -->
+<template>
+  <button @click="internalClick">
+    <slot />
+  </button>
+</template>
+
+<script setup>
+const emit = defineEmits(['action'])
+
+function internalClick() {
+  // This runs first
+  emit('action')
+  console.log('Internal click handler')
+}
+</script>
+
+<!-- Parent.vue -->
+<template>
+  <BaseButton @click="parentClick">Submit</BaseButton>
+</template>
+
+<script setup>
+function parentClick() {
+  // This ALSO runs (after internal)
+  submitForm()  // Might cause double submission!
+  console.log('Parent click handler')
+}
+</script>
+
+<!--
+  RESULT: Both handlers fire!
+  Console output:
+  1. "Internal click handler"
+  2. "Parent click handler"
+
+  If both trigger API calls, you get duplicate requests
+-->
+```
+
+## Good Code
+
+### Option 1: Prevent fallthrough with inheritAttrs: false
+
+```vue
+<!-- BaseButton.vue - Control event handling explicitly -->
+<script setup>
+defineOptions({
+  inheritAttrs: false
+})
+
+const emit = defineEmits(['click'])
+
+function handleClick(event) {
+  // Component controls all click behavior
+  console.log('Handled internally')
+  emit('click', event)  // Explicitly forward if needed
+}
+</script>
+
+<template>
+  <button @click="handleClick">
+    <slot />
+  </button>
+</template>
+```
+
+### Option 2: Document the additive behavior
+
+```vue
+<!-- BaseButton.vue - Design for composition -->
+<script setup>
+/**
+ * BaseButton - A composable button component
+ *
+ * Note: Click handlers passed to this component are ADDITIVE.
+ * The internal handler runs first, then any parent @click handler.
+ * Use @action event if you only want to respond to the action.
+ */
+const emit = defineEmits(['action'])
+
+function internalClick() {
+  // Internal logic (e.g., ripple effect, analytics)
+  emit('action')
+}
+</script>
+
+<template>
+  <button @click="internalClick">
+    <slot />
+  </button>
+</template>
+
+<!-- Parent.vue - Use the custom event instead -->
+<template>
+  <!-- Use @action, not @click, to avoid double handling -->
+  <BaseButton @action="handleAction">Submit</BaseButton>
+</template>
+```
+
+### Option 3: Use stopPropagation if needed
+
+```vue
+<!-- BaseButton.vue - Stop event propagation when needed -->
+<script setup>
+const props = defineProps({
+  stopPropagation: Boolean
+})
+
+function handleClick(event) {
+  if (props.stopPropagation) {
+    event.stopPropagation()
+  }
+  // Internal handling...
+}
+</script>
+
+<template>
+  <button @click="handleClick">
+    <slot />
+  </button>
+</template>
+```
+
+## Using Additive Behavior Intentionally
+
+The additive behavior can be useful for extending functionality:
+
+```vue
+<!-- EnhancedButton.vue - Leveraging additive listeners -->
+<template>
+  <button
+    @click="trackClick"
+    @focus="trackFocus"
+  >
+    <slot />
+  </button>
+</template>
+
+<script setup>
+function trackClick() {
+  analytics.track('button_click')
+  // Parent's @click will also run - that's intentional!
+}
+
+function trackFocus() {
+  analytics.track('button_focus')
+}
+</script>
+
+<!-- Parent.vue -->
+<template>
+  <!-- Both analytics AND form submission happen -->
+  <EnhancedButton @click="submitForm">Submit</EnhancedButton>
+</template>
+```
+
+## Execution Order
+
+```vue
+<script setup>
+// Component
+function componentHandler() {
+  console.log('1. Component handler (first)')
+}
+</script>
+
+<template>
+  <button @click="componentHandler">Click</button>
+</template>
+
+<!-- Parent passes @click -->
+<!-- Execution order:
+     1. componentHandler (defined in component)
+     2. parentHandler (passed as fallthrough)
+-->
+```
+
+## Best Practices
+
+1. **For UI components**: Use `inheritAttrs: false` and emit custom events
+2. **For HOCs/wrappers**: Document that listeners are additive
+3. **For analytics/tracking**: Leverage additive behavior intentionally
+4. **Avoid side effects**: Don't assume your handler is the only one running
+
+## References
+
+- [Fallthrough Attributes - v-on Listener Inheritance](https://vuejs.org/guide/components/attrs.html#v-on-listener-inheritance)
+- [Component Events](https://vuejs.org/guide/components/events.html)