@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/lifecycle-ssr-awareness.md

@@ -0,0 +1,184 @@
+---
+title: Mounted and Unmounted Hooks Do Not Run During SSR
+impact: MEDIUM
+impactDescription: SSR applications may fail if mounted-only code is essential for functionality
+type: capability
+tags: [vue3, lifecycle, ssr, server-side-rendering, nuxt, onMounted, mounted, hydration]
+---
+
+# Mounted and Unmounted Hooks Do Not Run During SSR
+
+**Impact: MEDIUM** - During server-side rendering (SSR), lifecycle hooks like `mounted`, `onMounted`, `unmounted`, and `onUnmounted` are never called on the server. This can cause differences between server-rendered and client-rendered content, hydration mismatches, and missing functionality if critical logic is placed only in these hooks.
+
+On the server, only `beforeCreate`, `created`, and their Composition API equivalents run. Client-specific operations (DOM access, browser APIs, third-party libraries) must be in mounted hooks, but you must handle the SSR case appropriately.
+
+## Task Checklist
+
+- [ ] Place browser-specific code (window, document, localStorage) in mounted/onMounted
+- [ ] Ensure critical data fetching happens in hooks that run on server (created)
+- [ ] Handle hydration mismatches for content that differs client vs server
+- [ ] Use `<ClientOnly>` wrapper (Nuxt) or conditional rendering for client-only components
+- [ ] Check for browser environment before using browser APIs
+
+**Incorrect:**
+```javascript
+// WRONG: Accessing browser APIs in created - breaks SSR
+export default {
+  created() {
+    // These don't exist on the server!
+    this.width = window.innerWidth // ReferenceError: window is not defined
+    this.savedData = localStorage.getItem('data') // ReferenceError: localStorage is not defined
+  }
+}
+```
+
+```javascript
+// WRONG: Critical initialization only in mounted - won't run on server
+export default {
+  data() {
+    return { user: null }
+  },
+  async mounted() {
+    // This won't run on server - page renders without user data
+    // Then hydrates with user data - causes flash of content
+    this.user = await fetchCurrentUser()
+  }
+}
+```
+
+**Correct:**
+```javascript
+// CORRECT: Data fetching in created (runs on server), DOM in mounted
+export default {
+  data() {
+    return {
+      user: null,
+      windowWidth: 0
+    }
+  },
+  async created() {
+    // This runs on both server and client
+    this.user = await fetchCurrentUser()
+  },
+  mounted() {
+    // Browser-specific code safely in mounted
+    this.windowWidth = window.innerWidth
+    window.addEventListener('resize', this.handleResize)
+  },
+  unmounted() {
+    window.removeEventListener('resize', this.handleResize)
+  }
+}
+```
+
+```vue
+<!-- CORRECT: Composition API with SSR awareness -->
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const user = ref(null)
+const windowWidth = ref(0)
+
+// This runs on both server and client (during setup)
+user.value = await useFetch('/api/user')
+
+// These only run on client
+onMounted(() => {
+  windowWidth.value = window.innerWidth
+  window.addEventListener('resize', handleResize)
+})
+
+onUnmounted(() => {
+  window.removeEventListener('resize', handleResize)
+})
+
+function handleResize() {
+  windowWidth.value = window.innerWidth
+}
+</script>
+```
+
+## Checking for Browser Environment
+
+```javascript
+// CORRECT: Guard browser API access
+export default {
+  data() {
+    return { theme: 'light' }
+  },
+  created() {
+    // Check if we're in browser before accessing browser APIs
+    if (typeof window !== 'undefined') {
+      this.theme = localStorage.getItem('theme') || 'light'
+    }
+  },
+  mounted() {
+    // mounted only runs in browser, so this is always safe
+    this.applyTheme()
+  }
+}
+```
+
+## Nuxt.js Specific Patterns
+
+```vue
+<!-- CORRECT: Using Nuxt's ClientOnly for client-specific components -->
+<template>
+  <div>
+    <!-- This content renders on both server and client -->
+    <h1>Dashboard</h1>
+
+    <!-- This only renders on client - no hydration mismatch -->
+    <ClientOnly>
+      <ChartComponent :data="chartData" />
+      <template #fallback>
+        <p>Loading chart...</p>
+      </template>
+    </ClientOnly>
+  </div>
+</template>
+```
+
+```javascript
+// CORRECT: Using Nuxt's process.client/process.server
+export default {
+  created() {
+    if (process.client) {
+      // Only runs in browser
+      this.initAnalytics()
+    }
+    if (process.server) {
+      // Only runs on server
+      this.logServerRequest()
+    }
+  }
+}
+```
+
+## Handling Hydration Mismatches
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+// Start with a value that matches what server renders
+const currentTime = ref(null)
+
+onMounted(() => {
+  // Update to real value only on client
+  // This prevents hydration mismatch
+  currentTime.value = new Date().toLocaleTimeString()
+})
+</script>
+
+<template>
+  <!-- Renders null on server, then updates on client -->
+  <span v-if="currentTime">{{ currentTime }}</span>
+  <span v-else>Loading...</span>
+</template>
+```
+
+## Reference
+- [Vue.js SSR Guide](https://vuejs.org/guide/scaling-up/ssr.html)
+- [Nuxt.js Lifecycle](https://nuxt.com/docs/api/composables/use-nuxt-app#lifecycle-hooks)
+- [Vue SSR Hydration](https://vuejs.org/guide/scaling-up/ssr.html#client-hydration)

package/skills/vue-debug-guides/reference/local-components-not-in-descendants.md

@@ -0,0 +1,151 @@
+---
+title: Locally Registered Components Are Not Available in Descendants
+impact: HIGH
+impactDescription: Common source of "component not found" errors in nested components
+type: gotcha
+tags: [vue3, component-registration, local-registration, scope, nested-components]
+---
+
+# Locally Registered Components Are Not Available in Descendants
+
+**Impact: HIGH** - Locally registered components are only available in the component where they are registered, NOT in its child or descendant components. This is a common source of "Unknown component" or "Failed to resolve component" errors when developers expect a component registered in a parent to be available in children.
+
+## Task Checklist
+
+- [ ] Import and register components in every file where they are used
+- [ ] Do not expect parent's local components to be available in children
+- [ ] If a component is needed in many places, consider global registration only as a last resort
+- [ ] Use IDE auto-import features to simplify repeated imports
+
+**Incorrect:**
+```vue
+<!-- ParentComponent.vue -->
+<script setup>
+import Card from './Card.vue'
+import ChildComponent from './ChildComponent.vue'
+</script>
+
+<template>
+  <Card>Parent content</Card>
+  <ChildComponent />
+</template>
+```
+
+```vue
+<!-- ChildComponent.vue -->
+<script setup>
+// WRONG: Expecting Card to be available because parent imported it
+// This will cause "Failed to resolve component: Card" error
+</script>
+
+<template>
+  <!-- ERROR: Card is not available here! -->
+  <Card>
+    Child content
+  </Card>
+</template>
+```
+
+**Correct:**
+```vue
+<!-- ParentComponent.vue -->
+<script setup>
+import Card from './Card.vue'
+import ChildComponent from './ChildComponent.vue'
+</script>
+
+<template>
+  <Card>Parent content</Card>
+  <ChildComponent />
+</template>
+```
+
+```vue
+<!-- ChildComponent.vue -->
+<script setup>
+// CORRECT: Each component must import what it uses
+import Card from './Card.vue'
+</script>
+
+<template>
+  <Card>
+    Child content
+  </Card>
+</template>
+```
+
+## Common Scenarios
+
+### Scenario 1: Deeply Nested Components
+```vue
+<!-- GrandchildComponent.vue -->
+<script setup>
+// Even if parent and grandparent both use Card,
+// grandchild must import it separately
+import Card from '@/components/Card.vue'
+import Button from '@/components/Button.vue'
+</script>
+
+<template>
+  <Card>
+    <Button>Click me</Button>
+  </Card>
+</template>
+```
+
+### Scenario 2: Slot Content with Components
+```vue
+<!-- Parent.vue -->
+<script setup>
+import Modal from './Modal.vue'
+import Form from './Form.vue'
+</script>
+
+<template>
+  <!-- Form is registered in Parent, so it works in slot content -->
+  <Modal>
+    <Form /> <!-- This works because slot content is compiled in Parent's scope -->
+  </Modal>
+</template>
+```
+
+```vue
+<!-- Modal.vue -->
+<script setup>
+// Modal doesn't need to import Form because slot content
+// is compiled in the parent's scope, not Modal's scope
+</script>
+
+<template>
+  <div class="modal">
+    <slot /> <!-- Form component works here because it's parent's slot content -->
+  </div>
+</template>
+```
+
+### Scenario 3: Dynamic Components
+```vue
+<!-- Container.vue -->
+<script setup>
+import TabA from './TabA.vue'
+import TabB from './TabB.vue'
+import { ref, shallowRef } from 'vue'
+
+// When using dynamic components, all possible components must be imported
+const currentTab = shallowRef(TabA)
+</script>
+
+<template>
+  <component :is="currentTab" />
+</template>
+```
+
+## Why This Design?
+
+Local registration provides:
+1. **Explicit dependencies** - You can see exactly what each component uses
+2. **Tree-shaking** - Unused components are removed from bundles
+3. **Clear scope** - No magic or implicit behavior
+
+## Reference
+- [Vue.js Component Registration - Local Registration](https://vuejs.org/guide/components/registration.html#local-registration)

package/skills/vue-debug-guides/reference/mount-return-value.md

@@ -0,0 +1,88 @@
+---
+title: mount() Returns Component Instance, Not App Instance
+impact: MEDIUM
+impactDescription: Using mount() return value for app configuration silently fails
+type: capability
+tags: [vue3, createApp, mount, api]
+---
+
+# mount() Returns Component Instance, Not App Instance
+
+**Impact: MEDIUM** - The `.mount()` method returns the root component instance, not the application instance. Attempting to chain app configuration methods after mount() will fail or produce unexpected behavior.
+
+This is a subtle API detail that catches developers who assume mount() returns the app for continued chaining.
+
+## Task Checklist
+
+- [ ] Never chain app configuration methods after mount()
+- [ ] If you need both instances, store them separately
+- [ ] Use the component instance for accessing root component state or methods
+- [ ] Use the app instance for configuration, plugins, and global registration
+
+**Incorrect:**
+```javascript
+import { createApp } from 'vue'
+import App from './App.vue'
+
+// WRONG: Assuming mount returns app instance
+const app = createApp(App).mount('#app')
+
+// This fails! app is actually the root component instance
+app.use(router)  // TypeError: app.use is not a function
+app.config.errorHandler = fn  // app.config is undefined
+```
+
+```javascript
+// WRONG: Trying to save both in one line
+const { app, component } = createApp(App).mount('#app')  // Doesn't work this way
+```
+
+**Correct:**
+```javascript
+import { createApp } from 'vue'
+import App from './App.vue'
+
+// Store app instance separately
+const app = createApp(App)
+
+// Configure the app
+app.use(router)
+app.config.errorHandler = (err) => console.error(err)
+
+// Store component instance if needed
+const rootComponent = app.mount('#app')
+
+// Now you have access to both:
+// - app: the application instance (for config, plugins)
+// - rootComponent: the root component instance (for state, methods)
+```
+
+```javascript
+// If you only need the app configured and mounted (most common case):
+createApp(App)
+  .use(router)
+  .use(pinia)
+  .mount('#app')  // Return value (component instance) discarded - that's fine
+```
+
+## When You Need the Root Component Instance
+
+```javascript
+const app = createApp(App)
+const vm = app.mount('#app')
+
+// Access root component's exposed state/methods
+console.log(vm.someExposedProperty)
+vm.someExposedMethod()
+
+// In Vue 3 with <script setup>, use defineExpose to expose:
+// <script setup>
+// import { ref } from 'vue'
+// const count = ref(0)
+// defineExpose({ count })
+// </script>
+```
+
+## Reference
+- [Vue.js - Mounting the App](https://vuejs.org/guide/essentials/application.html#mounting-the-app)
+- [Vue.js Application API - mount()](https://vuejs.org/api/application.html#app-mount)

package/skills/vue-debug-guides/reference/multi-root-component-class-attrs.md

@@ -0,0 +1,93 @@
+# Multi-Root Component Class Attribute Inheritance
+
+## Rule
+
+When a Vue 3 component has multiple root elements, class and style bindings from the parent will NOT automatically fall through. You must explicitly bind `$attrs.class` or `$attrs.style` to the target element.
+
+## Why This Matters
+
+- Vue 3 components can have multiple root elements (fragments)
+- Unlike single-root components, multi-root components have no automatic attribute fallthrough
+- Without explicit handling, classes and styles passed from parent are silently ignored
+- Vue will emit a runtime warning, but styles/classes simply won't apply
+
+## Bad Code
+
+```vue
+<!-- ChildComponent.vue - WRONG: classes from parent won't apply -->
+<template>
+  <header>Header</header>
+  <main>Content</main>
+  <footer>Footer</footer>
+</template>
+
+<!-- Parent usage -->
+<ChildComponent class="my-custom-class" />
+<!-- Result: my-custom-class is NOT applied to any element -->
+```
+
+## Good Code
+
+```vue
+<!-- ChildComponent.vue - CORRECT: explicitly bind $attrs.class -->
+<template>
+  <header>Header</header>
+  <main :class="$attrs.class" :style="$attrs.style">Content</main>
+  <footer>Footer</footer>
+</template>
+
+<!-- Or bind all attrs to one element -->
+<template>
+  <header>Header</header>
+  <main v-bind="$attrs">Content</main>
+  <footer>Footer</footer>
+</template>
+```
+
+## Accessing $attrs in script setup
+
+```vue
+<script setup>
+import { useAttrs } from 'vue'
+const attrs = useAttrs()
+// attrs.class and attrs.style are available
+</script>
+
+<template>
+  <header>Header</header>
+  <main :class="attrs.class">Content</main>
+  <footer>Footer</footer>
+</template>
+```
+
+## Disabling Automatic Inheritance
+
+For single-root components where you want to control attribute placement:
+
+```vue
+<script>
+export default {
+  inheritAttrs: false
+}
+</script>
+
+<script setup>
+import { useAttrs } from 'vue'
+const attrs = useAttrs()
+</script>
+
+<template>
+  <div class="wrapper">
+    <input v-bind="attrs" />
+  </div>
+</template>
+```
+
+## Vue 2 to Vue 3 Migration Note
+
+In Vue 2, `$attrs` did NOT include `class` and `style`. In Vue 3, `$attrs` contains ALL attributes including `class` and `style`. This is a breaking change that affects how you handle attribute forwarding.
+
+## References
+
+- [Fallthrough Attributes](https://vuejs.org/guide/components/attrs.html)
+- [Vue 3 Migration Guide - $attrs includes class & style](https://v3-migration.vuejs.org/breaking-changes/attrs-includes-class-style)

package/skills/vue-debug-guides/reference/native-event-collision-with-emits.md

@@ -0,0 +1,162 @@
+---
+title: Declaring Native Event Names in Emits Blocks Native Listeners
+impact: MEDIUM
+impactDescription: Declaring native events like 'click' in emits prevents native DOM event listeners from working
+type: gotcha
+tags: [vue3, emits, native-events, click, event-collision]
+---
+
+# Declaring Native Event Names in Emits Blocks Native Listeners
+
+**Impact: MEDIUM** - When you declare a native DOM event name (like `click`, `input`, `focus`) in your component's `emits` option, listeners for that event will ONLY respond to your component's `emit()` calls. They will no longer respond to the actual native DOM events on the root element.
+
+This can cause unexpected behavior where clicks seem to stop working on your component.
+
+## Task Checklist
+
+- [ ] Understand that declaring native event names changes listener behavior
+- [ ] Always emit the event when you declare it
+- [ ] Don't declare native events if you want fallthrough behavior
+- [ ] Test click/input handling after adding emits declarations
+
+## The Problem
+
+**Incorrect - Declaring but not emitting:**
+```vue
+<!-- ClickableCard.vue -->
+<script setup>
+// Declared 'click' but never emit it!
+const emit = defineEmits(['click', 'select'])
+</script>
+
+<template>
+  <div class="card">
+    <slot></slot>
+  </div>
+</template>
+```
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <!-- This NEVER fires! Native clicks are blocked -->
+  <ClickableCard @click="handleClick">
+    Click me
+  </ClickableCard>
+</template>
+```
+
+**Why it fails:**
+1. `click` is declared in `emits`
+2. Vue treats `@click` as a component event listener
+3. Native click on the `<div>` doesn't trigger component event
+4. Since `emit('click')` is never called, handler never fires
+
+## The Solution
+
+**Option 1: Emit the event explicitly:**
+```vue
+<!-- ClickableCard.vue -->
+<script setup>
+const emit = defineEmits(['click', 'select'])
+</script>
+
+<template>
+  <!-- Explicitly emit click when div is clicked -->
+  <div class="card" @click="emit('click', $event)">
+    <slot></slot>
+  </div>
+</template>
+```
+
+**Option 2: Don't declare native events (use fallthrough):**
+```vue
+<!-- ClickableCard.vue -->
+<script setup>
+// Only declare custom events, not native ones
+const emit = defineEmits(['select', 'custom-action'])
+</script>
+
+<template>
+  <!-- Native @click from parent falls through to this div -->
+  <div class="card">
+    <slot></slot>
+  </div>
+</template>
+```
+
+```vue
+<!-- Parent.vue -->
+<template>
+  <!-- Native click falls through and works -->
+  <ClickableCard @click="handleClick">
+    Click me
+  </ClickableCard>
+</template>
+```
+
+## Native Events Affected
+
+This applies to any native DOM event you might declare:
+
+| Event | Behavior When Declared |
+|-------|----------------------|
+| `click` | Only responds to `emit('click')`, not native clicks |
+| `input` | Only responds to `emit('input')`, not native input |
+| `change` | Only responds to `emit('change')`, not native change |
+| `focus` | Only responds to `emit('focus')`, not native focus |
+| `blur` | Only responds to `emit('blur')`, not native blur |
+| `submit` | Only responds to `emit('submit')`, not native form submit |
+| `keydown` | Only responds to `emit('keydown')`, not native keydown |
+
+## When This Is Intentional
+
+Sometimes you WANT to intercept native events:
+
+```vue
+<!-- CustomInput.vue -->
+<script setup>
+// Intentionally intercept 'input' to transform the value
+const emit = defineEmits(['input', 'update:modelValue'])
+
+function handleInput(event) {
+  const transformedValue = event.target.value.toUpperCase()
+  emit('input', transformedValue) // Emit transformed value, not raw event
+  emit('update:modelValue', transformedValue)
+}
+</script>
+
+<template>
+  <input @input="handleInput" />
+</template>
+```
+
+Here, declaring `input` is correct because you want to intercept and transform the native event before passing it to the parent.
+
+## Debugging Tips
+
+If your click handlers aren't firing:
+
+1. Check if the event is declared in `emits`
+2. If declared, ensure you're calling `emit('click')` somewhere
+3. If you want native behavior, remove from `emits` declaration
+4. Use Vue DevTools to see which events are being emitted
+
+```vue
+<script setup>
+const emit = defineEmits(['click'])
+
+function handleClick(event) {
+  console.log('Native click received, now emitting component event')
+  emit('click', event)
+}
+</script>
+
+<template>
+  <div @click="handleClick">Click me</div>
+</template>
+```
+
+## Reference
+- [Vue.js Component Events](https://vuejs.org/guide/components/events.html)
+- [Vue.js Fallthrough Attributes](https://vuejs.org/guide/components/attrs.html)