@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/no-passive-with-prevent.md

@@ -0,0 +1,141 @@
+---
+title: Never Use .passive and .prevent Together
+impact: HIGH
+impactDescription: Conflicting modifiers cause .prevent to be ignored and trigger browser warnings
+type: gotcha
+tags: [vue3, events, modifiers, scroll, touch, performance]
+---
+
+# Never Use .passive and .prevent Together
+
+**Impact: HIGH** - The `.passive` modifier tells the browser you will NOT call `preventDefault()`, while `.prevent` does exactly that. Using them together causes `.prevent` to be ignored and triggers browser console warnings. This is a logical contradiction that leads to broken event handling.
+
+## Task Checklist
+
+- [ ] Never combine `.passive` and `.prevent` on the same event
+- [ ] Use `.passive` for scroll/touch events where you want better performance
+- [ ] Use `.prevent` when you need to stop the default browser action
+- [ ] If you need conditional prevention, handle it in JavaScript without `.passive`
+
+**Incorrect:**
+```html
+<!-- WRONG: Conflicting modifiers -->
+<template>
+  <div @scroll.passive.prevent="handleScroll">
+    <!-- .prevent will be IGNORED -->
+    <!-- Browser shows warning -->
+  </div>
+</template>
+```
+
+```html
+<!-- WRONG: On touch events -->
+<template>
+  <div @touchstart.passive.prevent="handleTouch">
+    <!-- Cannot prevent default - passive already promised not to -->
+  </div>
+</template>
+```
+
+```html
+<!-- WRONG: On wheel events -->
+<template>
+  <div @wheel.passive.prevent="handleWheel">
+    <!-- Broken: will scroll anyway despite .prevent -->
+  </div>
+</template>
+```
+
+**Correct:**
+```html
+<!-- CORRECT: Use .passive for performance (no prevention needed) -->
+<template>
+  <div @scroll.passive="handleScroll">
+    <!-- Good for scroll tracking without blocking -->
+  </div>
+</template>
+```
+
+```html
+<!-- CORRECT: Use .prevent when you need to prevent default -->
+<template>
+  <form @submit.prevent="handleSubmit">
+    <!-- Correctly prevents form submission -->
+  </form>
+</template>
+```
+
+```html
+<!-- CORRECT: For touch events where you need to prevent -->
+<template>
+  <div @touchmove="handleTouchMove">
+    <!-- Handle prevention conditionally in JS -->
+  </div>
+</template>
+
+<script setup>
+function handleTouchMove(event) {
+  if (shouldPreventScroll.value) {
+    event.preventDefault()
+  }
+  // ... handle touch
+}
+</script>
+```
+
+## Understanding .passive
+
+```javascript
+// .passive tells the browser:
+// "I promise I won't call preventDefault()"
+
+// This allows the browser to:
+// 1. Start scrolling immediately without waiting for JS
+// 2. Improve scroll performance, especially on mobile
+// 3. Reduce jank and stuttering
+
+// Equivalent to:
+element.addEventListener('scroll', handler, { passive: true })
+```
+
+## When to Use .passive
+
+```html
+<!-- Good use cases for .passive -->
+
+<!-- Scroll tracking analytics -->
+<div @scroll.passive="trackScrollPosition">
+
+<!-- Touch gesture detection (no prevention needed) -->
+<div @touchmove.passive="detectGesture">
+
+<!-- Wheel event monitoring -->
+<div @wheel.passive="monitorWheel">
+```
+
+## When to Use .prevent (Without .passive)
+
+```html
+<!-- Good use cases for .prevent -->
+
+<!-- Form submission -->
+<form @submit.prevent="handleSubmit">
+
+<!-- Link clicks with custom navigation -->
+<a @click.prevent="navigate">
+
+<!-- Preventing context menu -->
+<div @contextmenu.prevent="showCustomMenu">
+```
+
+## Browser Warning
+
+When you combine `.passive` and `.prevent`, the browser console shows:
+```
+[Intervention] Unable to preventDefault inside passive event listener
+due to target being treated as passive.
+```
+
+## Reference
+- [Vue.js Event Handling - Event Modifiers](https://vuejs.org/guide/essentials/event-handling.html#event-modifiers)
+- [MDN - Improving scroll performance with passive listeners](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#improving_scrolling_performance_with_passive_listeners)

package/skills/vue-debug-guides/reference/no-v-if-with-v-for.md

@@ -0,0 +1,136 @@
+---
+title: Never Use v-if and v-for on the Same Element
+impact: HIGH
+impactDescription: Causes confusing precedence issues and Vue 2 to 3 migration bugs
+type: capability
+tags: [vue3, v-if, v-for, conditional-rendering, list-rendering, eslint]
+---
+
+# Never Use v-if and v-for on the Same Element
+
+**Impact: HIGH** - Using `v-if` and `v-for` on the same element creates ambiguous precedence that differs between Vue 2 and Vue 3. In Vue 2, `v-for` had higher precedence; in Vue 3, `v-if` has higher precedence. This breaking change causes subtle bugs during migration and makes code intent unclear.
+
+The ESLint rule `vue/no-use-v-if-with-v-for` enforces this best practice.
+
+## Task Checklist
+
+- [ ] Never place v-if and v-for on the same element
+- [ ] For filtering list items: use a computed property that filters the array
+- [ ] For hiding entire list: wrap with `<template v-if>` around the v-for
+- [ ] Enable eslint-plugin-vue rule `vue/no-use-v-if-with-v-for`
+
+**Incorrect:**
+```html
+<!-- WRONG: v-if and v-for on same element - ambiguous precedence -->
+<template>
+  <!-- Intent: show only active users -->
+  <li v-for="user in users" v-if="user.isActive" :key="user.id">
+    {{ user.name }}
+  </li>
+</template>
+```
+
+```html
+<!-- WRONG: Hiding entire list conditionally -->
+<template>
+  <li v-for="user in users" v-if="shouldShowList" :key="user.id">
+    {{ user.name }}
+  </li>
+</template>
+```
+
+```html
+<!-- WRONG: Vue 3 precedence issue -->
+<template>
+  <!-- In Vue 3, v-if runs FIRST, so 'user' is undefined! -->
+  <li v-for="user in users" v-if="user.isActive" :key="user.id">
+    {{ user.name }}
+  </li>
+  <!-- Error: Cannot read property 'isActive' of undefined -->
+</template>
+```
+
+**Correct:**
+```html
+<!-- CORRECT: Filter with computed property -->
+<template>
+  <li v-for="user in activeUsers" :key="user.id">
+    {{ user.name }}
+  </li>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+
+const props = defineProps(['users'])
+
+const activeUsers = computed(() =>
+  props.users.filter(user => user.isActive)
+)
+</script>
+```
+
+```html
+<!-- CORRECT: Wrap with <template v-if> for conditional list -->
+<template>
+  <template v-if="shouldShowList">
+    <li v-for="user in users" :key="user.id">
+      {{ user.name }}
+    </li>
+  </template>
+</template>
+```
+
+```html
+<!-- CORRECT: v-if inside the loop (per-item condition) -->
+<template>
+  <ul>
+    <template v-for="user in users" :key="user.id">
+      <li v-if="user.isActive">
+        {{ user.name }}
+      </li>
+    </template>
+  </ul>
+</template>
+```
+
+## Vue 2 vs Vue 3 Precedence Change
+
+```javascript
+// Vue 2: v-for evaluated first
+// <li v-for="user in users" v-if="user.isActive">
+// Equivalent to: users.forEach(user => { if (user.isActive) render(user) })
+
+// Vue 3: v-if evaluated first
+// <li v-for="user in users" v-if="user.isActive">
+// Equivalent to: if (user.isActive) users.forEach(user => render(user))
+// Problem: 'user' doesn't exist yet when v-if runs!
+```
+
+## Why Computed Properties Are Better
+
+```javascript
+// Benefits of filtering via computed:
+// 1. Clear separation of concerns (logic vs template)
+// 2. Cached - only recalculates when dependencies change
+// 3. Reusable - can be used elsewhere in component
+// 4. Testable - can unit test the filtering logic
+// 5. No ambiguity about intent
+
+const activeUsers = computed(() =>
+  users.value.filter(u => u.isActive)
+)
+
+// Can add more complex filtering
+const filteredUsers = computed(() =>
+  users.value
+    .filter(u => u.isActive)
+    .filter(u => u.role === selectedRole.value)
+    .sort((a, b) => a.name.localeCompare(b.name))
+)
+```
+
+## Reference
+- [Vue.js Style Guide - Avoid v-if with v-for](https://vuejs.org/style-guide/rules-essential.html#avoid-v-if-with-v-for)
+- [Vue 3 Migration Guide - v-if vs v-for Precedence](https://v3-migration.vuejs.org/breaking-changes/v-if-v-for)
+- [ESLint Plugin Vue - no-use-v-if-with-v-for](https://eslint.vuejs.org/rules/no-use-v-if-with-v-for)

package/skills/vue-debug-guides/reference/perf-computed-object-stability.md

@@ -0,0 +1,157 @@
+---
+title: Return Stable Object References from Computed Properties
+impact: MEDIUM
+impactDescription: Computed properties returning new objects trigger effects even when values haven't meaningfully changed
+type: efficiency
+tags: [vue3, computed, performance, reactivity, vue3.4]
+---
+
+# Return Stable Object References from Computed Properties
+
+**Impact: MEDIUM** - In Vue 3.4+, computed properties only trigger effects when their value changes. However, if a computed returns a new object each time, Vue cannot detect that the values inside are the same. This causes unnecessary effect re-runs.
+
+For primitive values, Vue 3.4+ handles this automatically. For objects, manually compare and return the previous value when nothing meaningful has changed.
+
+## Task Checklist
+
+- [ ] For computed properties returning primitives, Vue 3.4+ handles stability automatically
+- [ ] For computed properties returning objects, compare with previous value and return old reference if unchanged
+- [ ] Always perform the full computation before comparing (to track dependencies correctly)
+- [ ] Consider if you really need to return an object, or if primitives would suffice
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, computed, watchEffect } from 'vue'
+
+const count = ref(0)
+
+// BAD: Returns new object every time, always triggers effects
+const stats = computed(() => {
+  return {
+    isEven: count.value % 2 === 0,
+    doubleValue: count.value * 2
+  }
+})
+
+watchEffect(() => {
+  console.log('Stats changed:', stats.value)
+  // Logs on EVERY count change, even when isEven hasn't changed
+  // count: 0 -> 2 -> 4: isEven is always true, but effect runs each time
+})
+</script>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, computed, watchEffect } from 'vue'
+
+const count = ref(0)
+
+// GOOD (Vue 3.4+): Primitive computed - automatic stability
+const isEven = computed(() => count.value % 2 === 0)
+
+watchEffect(() => {
+  console.log('isEven:', isEven.value)
+  // Only logs when isEven actually changes (0, 2, 4 won't re-trigger)
+})
+
+// GOOD (Vue 3.4+): Manual comparison for object returns
+const stats = computed((oldValue) => {
+  // Step 1: Always compute the new value first (to track dependencies)
+  const newValue = {
+    isEven: count.value % 2 === 0,
+    category: count.value < 10 ? 'small' : 'large'
+  }
+
+  // Step 2: Compare with previous value
+  if (oldValue &&
+      oldValue.isEven === newValue.isEven &&
+      oldValue.category === newValue.category) {
+    return oldValue  // Return old reference - no effect triggers
+  }
+
+  return newValue
+})
+
+watchEffect(() => {
+  console.log('Stats changed:', stats.value)
+  // Now only logs when isEven or category actually changes
+})
+</script>
+```
+
+## Primitive vs Object Computed Behavior (Vue 3.4+)
+
+```javascript
+import { ref, computed, watchEffect } from 'vue'
+
+const count = ref(0)
+
+// PRIMITIVE: Vue automatically detects value hasn't changed
+const isEven = computed(() => count.value % 2 === 0)
+
+watchEffect(() => console.log(isEven.value))  // true
+
+count.value = 2  // isEven still true - NO log
+count.value = 4  // isEven still true - NO log
+count.value = 3  // isEven now false - logs: false
+
+// OBJECT: New reference every time (without manual comparison)
+const obj = computed(() => ({ isEven: count.value % 2 === 0 }))
+
+watchEffect(() => console.log(obj.value))  // { isEven: true }
+
+count.value = 2  // Logs again! New object reference
+count.value = 4  // Logs again! New object reference
+```
+
+## Advanced: Deep Object Comparison
+
+```javascript
+import { ref, computed } from 'vue'
+import { isEqual } from 'lodash-es'  // For deep comparison
+
+const filters = ref({ category: 'all', sortBy: 'date', page: 1 })
+
+// For complex objects, use deep comparison
+const activeFilters = computed((oldValue) => {
+  const newValue = {
+    ...filters.value,
+    hasFilters: filters.value.category !== 'all' || filters.value.sortBy !== 'date'
+  }
+
+  // Deep compare for complex objects
+  if (oldValue && isEqual(oldValue, newValue)) {
+    return oldValue
+  }
+
+  return newValue
+})
+```
+
+## Important: Always Compute Before Comparing
+
+```javascript
+// BAD: Early return prevents dependency tracking
+const optimized = computed((oldValue) => {
+  if (oldValue && someCondition) {
+    return oldValue  // Dependencies not tracked!
+  }
+  return computeExpensiveValue()
+})
+
+// GOOD: Compute first, then compare
+const optimized = computed((oldValue) => {
+  const newValue = computeExpensiveValue()  // Always track dependencies
+  if (oldValue && newValue === oldValue) {
+    return oldValue
+  }
+  return newValue
+})
+```
+
+## Reference
+- [Vue.js Performance - Computed Stability](https://vuejs.org/guide/best-practices/performance.html#computed-stability)
+- [Vue.js Computed Properties](https://vuejs.org/guide/essentials/computed.html)

package/skills/vue-debug-guides/reference/perf-props-stability-update-optimization.md

@@ -0,0 +1,140 @@
+---
+title: Keep Props Stable to Minimize Child Re-renders
+impact: HIGH
+impactDescription: Passing changing props to list items causes ALL children to re-render unnecessarily
+type: efficiency
+tags: [vue3, performance, props, v-for, re-renders, optimization]
+---
+
+# Keep Props Stable to Minimize Child Re-renders
+
+**Impact: HIGH** - When props passed to child components change, Vue must re-render those components. Passing derived values like `activeId` to every list item causes all items to re-render when activeId changes, even if only one item's active state actually changed.
+
+Move comparison logic to the parent and pass the boolean result instead. This is one of the most impactful update performance optimizations in Vue.
+
+## Task Checklist
+
+- [ ] Avoid passing parent-level state that all children compare against (like `activeId`)
+- [ ] Pre-compute derived boolean props in the parent (like `:active="item.id === activeId"`)
+- [ ] Profile re-renders using Vue DevTools to identify prop stability issues
+- [ ] Consider this pattern especially critical for large lists
+
+**Incorrect:**
+```vue
+<template>
+  <!-- BAD: activeId changes -> ALL 100 ListItems re-render -->
+  <ListItem
+    v-for="item in list"
+    :key="item.id"
+    :id="item.id"
+    :active-id="activeId"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const list = ref([/* 100 items */])
+const activeId = ref(null)
+
+// When activeId changes from 1 to 2:
+// - ListItem 1 needs to re-render (was active, now not)
+// - ListItem 2 needs to re-render (was not active, now active)
+// - All other 98 ListItems ALSO re-render because activeId prop changed!
+</script>
+```
+
+```vue
+<!-- ListItem.vue - receives activeId and compares internally -->
+<template>
+  <div :class="{ active: id === activeId }">
+    {{ id }}
+  </div>
+</template>
+
+<script setup>
+defineProps({
+  id: Number,
+  activeId: Number  // This prop changes for ALL items
+})
+</script>
+```
+
+**Correct:**
+```vue
+<template>
+  <!-- GOOD: Only items whose :active actually changed will re-render -->
+  <ListItem
+    v-for="item in list"
+    :key="item.id"
+    :id="item.id"
+    :active="item.id === activeId"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const list = ref([/* 100 items */])
+const activeId = ref(null)
+
+// When activeId changes from 1 to 2:
+// - ListItem 1: :active changed from true to false -> re-renders
+// - ListItem 2: :active changed from false to true -> re-renders
+// - All other 98 ListItems: :active is still false -> NO re-render!
+</script>
+```
+
+```vue
+<!-- ListItem.vue - receives pre-computed boolean -->
+<template>
+  <div :class="{ active }">
+    {{ id }}
+  </div>
+</template>
+
+<script setup>
+defineProps({
+  id: Number,
+  active: Boolean  // This only changes for items that truly changed
+})
+</script>
+```
+
+## Common Patterns That Cause Prop Instability
+
+```vue
+<!-- BAD: Passing index that could shift -->
+<Item
+  v-for="(item, index) in items"
+  :key="item.id"
+  :index="index"
+  :total="items.length"  <!-- Changes when list changes -->
+/>
+
+<!-- BAD: Passing entire selection set -->
+<Item
+  v-for="item in items"
+  :key="item.id"
+  :selected-ids="selectedIds"  <!-- All items re-render on any selection -->
+/>
+
+<!-- GOOD: Pre-compute the boolean -->
+<Item
+  v-for="item in items"
+  :key="item.id"
+  :selected="selectedIds.includes(item.id)"
+/>
+```
+
+## Performance Impact Example
+
+| Scenario | Props Changed | Components Re-rendered |
+|----------|---------------|------------------------|
+| 100 items, pass `activeId` | 100 | 100 (all) |
+| 100 items, pass `:active` boolean | 2 | 2 (only changed) |
+| 1000 items, pass `activeId` | 1000 | 1000 (all) |
+| 1000 items, pass `:active` boolean | 2 | 2 (only changed) |
+
+## Reference
+- [Vue.js Performance - Props Stability](https://vuejs.org/guide/best-practices/performance.html#props-stability)

package/skills/vue-debug-guides/reference/plugin-global-properties-sparingly.md

@@ -0,0 +1,109 @@
+# Use Global Properties Sparingly in Plugins
+
+## Rule
+
+When using `app.config.globalProperties` in Vue plugins, use them sparingly and with clear naming conventions. Excessive global properties lead to confusion, naming conflicts, and debugging difficulties.
+
+## Why This Matters
+
+1. **Implicit dependencies**: Global properties make component dependencies invisible, making code harder to understand and maintain.
+
+2. **Naming collisions**: Multiple plugins may try to use the same property name (e.g., `$http`, `$api`), causing silent overwrites.
+
+3. **Debugging difficulty**: When issues arise, tracing back to which plugin provides a global property is challenging.
+
+4. **IDE limitations**: Global properties may not have proper autocomplete or type checking without careful configuration.
+
+5. **Testing complexity**: Global state is harder to mock and isolate in unit tests.
+
+## Bad Practice
+
+```typescript
+// Too many global properties from various plugins
+app.config.globalProperties.$http = axios
+app.config.globalProperties.$api = apiClient
+app.config.globalProperties.$auth = authService
+app.config.globalProperties.$translate = i18n.translate
+app.config.globalProperties.$format = formatters
+app.config.globalProperties.$utils = utilities
+app.config.globalProperties.$config = appConfig
+app.config.globalProperties.$logger = logger
+
+// In component - where did all these come from?
+export default {
+  mounted() {
+    this.$logger.info('Mounted')
+    const data = await this.$http.get(this.$config.apiUrl)
+    this.$api.process(this.$utils.transform(data))
+  }
+}
+```
+
+## Good Practice
+
+```typescript
+// Use provide/inject for most functionality
+export default {
+  install(app, options) {
+    // Provide services via injection
+    app.provide('api', apiClient)
+    app.provide('auth', authService)
+    app.provide('i18n', i18n)
+
+    // Reserve globalProperties for truly global template helpers
+    // that are used extensively in templates across the app
+    app.config.globalProperties.$t = i18n.translate  // Common convention
+  }
+}
+
+// In component - explicit dependencies
+<script setup>
+import { inject } from 'vue'
+
+const api = inject('api')
+const auth = inject('auth')
+</script>
+
+<template>
+  <!-- $t is acceptable for common template-only usage -->
+  <h1>{{ $t('welcome') }}</h1>
+</template>
+```
+
+## Naming Conventions
+
+If you do use globalProperties:
+
+1. **Use `$` prefix**: This is the Vue convention and avoids conflicts with component data/methods
+2. **Use unique prefixes for your library**: e.g., `$myLib_translate` for third-party plugins
+3. **Document all global properties**: Keep a central registry of what each plugin provides
+
+```typescript
+// Good: namespaced to avoid conflicts
+app.config.globalProperties.$myPlugin = {
+  translate: (key) => /* ... */,
+  format: (value) => /* ... */
+}
+
+// Usage
+{{ $myPlugin.translate('key') }}
+```
+
+## Auditing Global Properties
+
+You can inspect all global properties for debugging:
+
+```typescript
+console.log(app.config.globalProperties)
+```
+
+## When Global Properties Are Acceptable
+
+1. **Template-only utilities** used very frequently (like `$t` for translations)
+2. **Legacy migration** when transitioning from Vue 2
+3. **Libraries that need Options API compatibility** (but prefer also providing inject)
+
+## References
+
+- [Vue.js Plugins Documentation](https://vuejs.org/guide/reusability/plugins.html)
+- [Vue.js Global Properties](https://vuejs.org/api/application.html#app-config-globalproperties)