@pythoughts/vue-skills-mcp 0.1.0

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

@@ -0,0 +1,160 @@
+---
+title: Never Mutate Computed Property Return Values
+impact: HIGH
+impactDescription: Mutating computed values causes silent failures and lost changes
+type: capability
+tags: [vue3, computed, reactivity, immutability, common-mistake]
+---
+
+# Never Mutate Computed Property Return Values
+
+**Impact: HIGH** - The returned value from a computed property is derived state - a temporary snapshot. Mutating this value leads to bugs that are difficult to debug.
+
+**Important:** Mutations DO persist while the computed cache remains valid, but are lost when recomputation occurs. The danger lies in unpredictable cache invalidation timing - any change to the computed's dependencies triggers recomputation, silently discarding your mutations. This makes bugs intermittent and hard to reproduce.
+
+Every time the source state changes, a new snapshot is created. Mutating a snapshot is meaningless because it will be discarded on the next recalculation.
+
+## Task Checklist
+
+- [ ] Treat computed return values as read-only
+- [ ] Update the source state instead of the computed value
+- [ ] Use writable computed properties if bidirectional binding is needed
+- [ ] Avoid array mutating methods (push, pop, splice, reverse, sort) on computed arrays
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const books = ref(['Vue Guide', 'React Handbook'])
+
+const publishedBooks = computed(() => {
+  return books.value.filter(book => book.includes('Guide'))
+})
+
+function addBook() {
+  // BAD: Mutating computed value - change will be lost!
+  publishedBooks.value.push('New Book')
+}
+
+// BAD: Mutating computed array
+const sortedBooks = computed(() => books.value.filter(b => b))
+
+function reverseBooks() {
+  // BAD: This mutates the computed snapshot
+  sortedBooks.value.reverse()
+}
+</script>
+```
+
+```vue
+<script>
+export default {
+  data() {
+    return {
+      author: {
+        name: 'John',
+        books: ['Book A', 'Book B']
+      }
+    }
+  },
+  computed: {
+    authorBooks() {
+      return this.author.books
+    }
+  },
+  methods: {
+    addBook() {
+      // BAD: Mutating computed value
+      this.authorBooks.push('New Book')
+    }
+  }
+}
+</script>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const books = ref(['Vue Guide', 'React Handbook'])
+
+const publishedBooks = computed(() => {
+  return books.value.filter(book => book.includes('Guide'))
+})
+
+function addBook(bookName) {
+  // GOOD: Update the source state
+  books.value.push(bookName)
+}
+
+// GOOD: Create a copy before mutating for display
+const sortedBooks = computed(() => {
+  return [...books.value].sort()  // Spread to create copy before sort
+})
+
+const reversedBooks = computed(() => {
+  return [...books.value].reverse()  // Spread to create copy before reverse
+})
+</script>
+```
+
+```vue
+<script>
+export default {
+  data() {
+    return {
+      author: {
+        name: 'John',
+        books: ['Book A', 'Book B']
+      }
+    }
+  },
+  computed: {
+    authorBooks() {
+      return this.author.books
+    }
+  },
+  methods: {
+    addBook(bookName) {
+      // GOOD: Update source state
+      this.author.books.push(bookName)
+    }
+  }
+}
+</script>
+```
+
+## Writable Computed for Bidirectional Binding
+
+If you genuinely need to "set" a computed value, use a writable computed property:
+
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+
+const firstName = ref('John')
+const lastName = ref('Doe')
+
+// Writable computed with getter and setter
+const fullName = computed({
+  get() {
+    return `${firstName.value} ${lastName.value}`
+  },
+  set(newValue) {
+    // Update source state based on the new value
+    const parts = newValue.split(' ')
+    firstName.value = parts[0] || ''
+    lastName.value = parts[1] || ''
+  }
+})
+
+// Now this is valid:
+fullName.value = 'Jane Smith'  // Updates firstName and lastName
+</script>
+```
+
+## Reference
+- [Vue.js Computed Properties - Avoid Mutating Computed Value](https://vuejs.org/guide/essentials/computed.html#avoid-mutating-computed-value)
+- [Vue.js Computed Properties - Writable Computed](https://vuejs.org/guide/essentials/computed.html#writable-computed)

package/skills/vue-debug-guides/reference/configure-app-before-mount.md

@@ -0,0 +1,89 @@
+---
+title: Configure Vue App Before Calling mount()
+impact: HIGH
+impactDescription: App configurations after mount() are silently ignored, causing missing plugins and handlers
+type: capability
+tags: [vue3, createApp, mount, configuration, setup]
+---
+
+# Configure Vue App Before Calling mount()
+
+**Impact: HIGH** - Any app configurations applied after `.mount()` is called are silently ignored. This includes error handlers, global components, directives, and plugins, leading to mysterious missing functionality.
+
+The `.mount()` method should always be called after all app configurations and asset registrations are done. This is a critical ordering requirement that, when violated, produces no errors but causes features to silently fail.
+
+## Task Checklist
+
+- [ ] Register all plugins (router, store, etc.) before mount()
+- [ ] Configure error handlers before mount()
+- [ ] Register global components and directives before mount()
+- [ ] Set all `app.config` properties before mount()
+- [ ] Call `.mount()` as the final step in app initialization
+
+**Incorrect:**
+```javascript
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
+
+// WRONG: Mounting first, then configuring
+app.mount('#app')
+
+// These are silently IGNORED - app is already mounted!
+app.use(router)
+app.config.errorHandler = (err) => {
+  console.error('Global error:', err)
+}
+app.component('GlobalButton', GlobalButton)
+```
+
+**Correct:**
+```javascript
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+import { createPinia } from 'pinia'
+import GlobalButton from './components/GlobalButton.vue'
+
+const app = createApp(App)
+
+// Configure everything FIRST
+app.use(router)
+app.use(createPinia())
+
+// Set up error handling
+app.config.errorHandler = (err, instance, info) => {
+  console.error('Global error:', err)
+  console.log('Component:', instance)
+  console.log('Error info:', info)
+}
+
+// Register global components
+app.component('GlobalButton', GlobalButton)
+
+// Mount LAST - after all configuration is complete
+app.mount('#app')
+```
+
+## Common Mistake: Chaining with Mount
+
+```javascript
+// WRONG: Chaining mount in the middle of configuration
+createApp(App)
+  .use(router)
+  .mount('#app')  // Everything after this line is a problem
+  .use(pinia)     // This doesn't even work - mount returns component instance!
+
+// CORRECT: Either complete chain before mount, or use intermediate variable
+createApp(App)
+  .use(router)
+  .use(pinia)
+  .component('GlobalButton', GlobalButton)
+  .mount('#app')  // Mount at the very end
+```
+
+## Reference
+- [Vue.js - Creating a Vue Application](https://vuejs.org/guide/essentials/application.html)
+- [Vue.js Application API](https://vuejs.org/api/application.html)

package/skills/vue-debug-guides/reference/declare-emits-for-documentation.md

@@ -0,0 +1,212 @@
+---
+title: Always Declare Emits for Documentation and Validation
+impact: MEDIUM
+impactDescription: Undeclared emits cause warnings, break TypeScript inference, and prevent event validation
+type: best-practice
+tags: [vue3, emits, defineEmits, component-events, typescript, documentation]
+---
+
+# Always Declare Emits for Documentation and Validation
+
+**Impact: MEDIUM** - Declaring emitted events with `defineEmits()` or the `emits` option is technically optional, but strongly recommended. Without declarations, Vue shows runtime warnings, TypeScript can't infer event types, and you lose the ability to validate event payloads.
+
+Declared emits also serve as self-documentation, making it immediately clear what events a component can emit.
+
+## Task Checklist
+
+- [ ] Use `defineEmits()` in `<script setup>` to declare all events
+- [ ] Use `emits` option when not using `<script setup>`
+- [ ] Add TypeScript types for event payloads
+- [ ] Consider adding validation functions for complex payloads
+- [ ] Document the purpose of each event
+
+## The Warning
+
+When you emit without declaring:
+
+```vue
+<script setup>
+// No defineEmits declaration
+function handleClick() {
+  emit('select', item) // Vue warns in dev mode
+}
+</script>
+```
+
+Vue warns:
+```
+[Vue warn]: Component emitted event "select" but it is neither declared
+in the emits option nor as an "onSelect" prop.
+```
+
+## Basic Declaration
+
+**Correct - Array syntax:**
+```vue
+<script setup>
+const emit = defineEmits(['submit', 'cancel', 'update'])
+
+function handleSubmit() {
+  emit('submit', formData)
+}
+
+function handleCancel() {
+  emit('cancel')
+}
+</script>
+```
+
+**Correct - Options API:**
+```js
+export default {
+  emits: ['submit', 'cancel', 'update'],
+
+  methods: {
+    handleSubmit() {
+      this.$emit('submit', this.formData)
+    }
+  }
+}
+```
+
+## TypeScript Typed Emits
+
+**Correct - Type-based declaration (recommended for TypeScript):**
+```vue
+<script setup lang="ts">
+interface User {
+  id: number
+  name: string
+}
+
+const emit = defineEmits<{
+  submit: [data: FormData]
+  cancel: []
+  'update:modelValue': [value: string]
+  select: [user: User, index: number]
+}>()
+
+// Now TypeScript enforces correct payloads
+emit('submit', formData) // OK
+emit('submit') // Error: Expected 1 argument
+emit('select', user) // Error: Expected 2 arguments
+emit('unknown') // Error: Unknown event
+</script>
+```
+
+**Alternative syntax (Vue 3.3+):**
+```vue
+<script setup lang="ts">
+const emit = defineEmits<{
+  (e: 'submit', data: FormData): void
+  (e: 'cancel'): void
+  (e: 'update:modelValue', value: string): void
+}>()
+</script>
+```
+
+## Event Validation
+
+You can validate event payloads at runtime:
+
+**Correct - Validation functions:**
+```vue
+<script setup>
+const emit = defineEmits({
+  // No validation, just declaration
+  cancel: null,
+
+  // Validate payload
+  submit: (payload) => {
+    if (!payload.email) {
+      console.warn('Submit event requires email')
+      return false
+    }
+    return true
+  },
+
+  // Validate with type checking
+  click: (id) => typeof id === 'number'
+})
+</script>
+```
+
+Returning `false` from a validator logs a console warning but doesn't prevent the event from being emitted.
+
+## Benefits of Declaring Emits
+
+### 1. Fallthrough Attribute Separation
+
+Without declaration, native event listeners fall through to the root element:
+
+```vue
+<!-- ParentComponent.vue -->
+<ChildComponent @click="handleClick" />
+```
+
+```vue
+<!-- ChildComponent.vue - WITHOUT emits declaration -->
+<template>
+  <!-- Native click listener falls through to button -->
+  <button>Click me</button>
+</template>
+```
+
+With declaration, Vue knows it's a component event:
+
+```vue
+<script setup>
+// Now Vue knows 'click' is a component event, not native
+const emit = defineEmits(['click'])
+</script>
+```
+
+### 2. Self-Documentation
+
+```vue
+<script setup>
+// Clear contract: this component emits these events
+const emit = defineEmits<{
+  'row-click': [row: TableRow]
+  'row-select': [row: TableRow, selected: boolean]
+  'page-change': [page: number]
+  'sort-change': [column: string, direction: 'asc' | 'desc']
+}>()
+</script>
+```
+
+### 3. IDE Support
+
+With declarations, your IDE can:
+- Autocomplete event names when using the component
+- Show event payload types
+- Warn about typos in event names
+- Navigate to event definitions
+
+## $emit in Template vs emit in Script
+
+```vue
+<script setup>
+// $emit is available in template, but...
+// emit() is needed in <script setup>
+const emit = defineEmits(['submit'])
+
+function handleSubmit() {
+  // $emit doesn't work here - use emit()
+  emit('submit', data)
+}
+</script>
+
+<template>
+  <!-- $emit works in template -->
+  <button @click="$emit('submit', data)">Submit</button>
+
+  <!-- Or use the declared emit function -->
+  <button @click="emit('submit', data)">Submit</button>
+</template>
+```
+
+## Reference
+- [Vue.js Component Events - Declaring Emitted Events](https://vuejs.org/guide/components/events.html#declaring-emitted-events)
+- [Vue.js Component Events - Events Validation](https://vuejs.org/guide/components/events.html#events-validation)
+- [Vue 3 Migration - emits Option](https://v3-migration.vuejs.org/breaking-changes/emits-option)

package/skills/vue-debug-guides/reference/define-expose-before-await.md

@@ -0,0 +1,192 @@
+---
+title: defineExpose Must Be Called Before Any Await
+impact: HIGH
+impactDescription: Properties exposed after await are inaccessible to parent component refs
+type: gotcha
+tags: [vue3, script-setup, defineExpose, async, component-refs]
+---
+
+# defineExpose Must Be Called Before Any Await
+
+**Impact: HIGH** - In `<script setup>`, if you call `defineExpose()` after an `await` statement, the exposed properties will NOT be accessible to parent components using template refs. This is a subtle async timing issue that causes silent failures.
+
+The compiler transforms top-level await, and code after await runs in a different execution context where defineExpose cannot properly register with the component instance.
+
+## Task Checklist
+
+- [ ] Always call defineExpose() at the top of script setup, before any await
+- [ ] If async data is needed in exposed methods, fetch it separately
+- [ ] Structure code so expose declarations come first
+- [ ] Test parent ref access when using async setup
+
+**Incorrect:**
+```vue
+<!-- ChildComponent.vue -->
+<script setup>
+import { ref } from 'vue'
+
+const data = ref(null)
+const count = ref(0)
+
+function increment() {
+  count.value++
+}
+
+// WRONG: await before defineExpose
+const response = await fetch('/api/data')
+data.value = await response.json()
+
+// BROKEN: This won't work - called after await!
+defineExpose({
+  count,
+  increment,
+  data
+})
+</script>
+
+<template>
+  <div>{{ data }}</div>
+</template>
+```
+
+```vue
+<!-- ParentComponent.vue -->
+<script setup>
+import { ref, onMounted } from 'vue'
+import ChildComponent from './ChildComponent.vue'
+
+const childRef = ref(null)
+
+onMounted(() => {
+  // FAILS: All exposed properties are undefined!
+  console.log(childRef.value.count) // undefined
+  childRef.value.increment() // TypeError
+})
+</script>
+
+<template>
+  <Suspense>
+    <ChildComponent ref="childRef" />
+  </Suspense>
+</template>
+```
+
+**Correct:**
+```vue
+<!-- ChildComponent.vue -->
+<script setup>
+import { ref } from 'vue'
+
+const data = ref(null)
+const count = ref(0)
+
+function increment() {
+  count.value++
+}
+
+// CORRECT: defineExpose BEFORE any await
+defineExpose({
+  count,
+  increment,
+  data
+})
+
+// Now safe to use await
+const response = await fetch('/api/data')
+data.value = await response.json()
+</script>
+
+<template>
+  <div>{{ data }}</div>
+</template>
+```
+
+```vue
+<!-- Alternative: Separate async logic from expose -->
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const data = ref(null)
+const loading = ref(true)
+
+function getData() {
+  return data.value
+}
+
+async function refreshData() {
+  loading.value = true
+  const response = await fetch('/api/data')
+  data.value = await response.json()
+  loading.value = false
+}
+
+// CORRECT: No await at top level - defineExpose always works
+defineExpose({
+  data,
+  getData,
+  refreshData,
+  loading
+})
+
+// Trigger async load in lifecycle hook instead
+onMounted(() => {
+  refreshData()
+})
+</script>
+
+<template>
+  <div v-if="loading">Loading...</div>
+  <div v-else>{{ data }}</div>
+</template>
+```
+
+```vue
+<!-- If you must use top-level await, define expose first -->
+<script setup>
+import { ref } from 'vue'
+
+const user = ref(null)
+const posts = ref([])
+
+// CORRECT: All expose calls come first
+defineExpose({
+  user,
+  posts,
+  refresh: () => loadData()
+})
+
+// Now safe to await
+async function loadData() {
+  const [userRes, postsRes] = await Promise.all([
+    fetch('/api/user'),
+    fetch('/api/posts')
+  ])
+  user.value = await userRes.json()
+  posts.value = await postsRes.json()
+}
+
+// Top-level await after defineExpose is safe
+await loadData()
+</script>
+```
+
+## Why This Happens
+
+Vue's compiler transforms `<script setup>` with top-level await into an async setup function. The component instance context is only available synchronously before the first await. After await, the execution resumes outside that context, making defineExpose ineffective.
+
+```javascript
+// What the compiler roughly generates:
+async setup() {
+  const count = ref(0)
+
+  // Context available here
+  await fetch(...)  // Suspends execution
+
+  // Context lost after resuming
+  defineExpose({ count }) // Too late!
+}
+```
+
+## Reference
+- [Vue.js Script Setup - defineExpose](https://vuejs.org/api/sfc-script-setup.html#defineexpose)
+- [Vue.js Async Components](https://vuejs.org/guide/components/async.html)