@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/provide-inject-synchronous-setup.md

@@ -0,0 +1,235 @@
+---
+title: Provide Must Be Called Synchronously During Setup
+impact: HIGH
+impactDescription: Calling provide() asynchronously or conditionally may fail silently or cause inconsistent injection behavior
+type: gotcha
+tags: [vue3, provide-inject, composition-api, async, setup]
+---
+
+# Provide Must Be Called Synchronously During Setup
+
+**Impact: HIGH** - The `provide()` function must be called synchronously during the component's `setup()` phase. Calling it asynchronously (inside callbacks, promises, or after await) will fail silently, and descendant components will not receive the provided value.
+
+## Task Checklist
+
+- [ ] Always call `provide()` at the top level of `setup()` or `<script setup>`
+- [ ] Never call `provide()` inside async callbacks or after await statements
+- [ ] For async data, provide a ref first, then update its value later
+- [ ] Use immediate `provide()` with reactive containers for dynamic data
+
+## The Gotcha: Async Provide Fails Silently
+
+**Wrong - Provide after async operation:**
+```vue
+<script setup>
+import { provide } from 'vue'
+
+// WRONG: provide() called after await - will NOT work
+onMounted(async () => {
+  const userData = await fetchUser()
+  provide('user', userData) // Silent failure!
+})
+</script>
+```
+
+**Wrong - Provide inside callback:**
+```vue
+<script setup>
+import { provide } from 'vue'
+
+// WRONG: provide() inside callback - will NOT work
+setTimeout(() => {
+  provide('config', { theme: 'dark' }) // Silent failure!
+}, 0)
+</script>
+```
+
+**Wrong - Provide after await in setup:**
+```vue
+<script setup>
+import { provide } from 'vue'
+
+const response = await fetch('/api/config')
+const config = await response.json()
+
+// WRONG: This is after an await, setup context may be lost
+provide('config', config) // May not work reliably
+</script>
+```
+
+## Solution: Provide Synchronously, Update Async
+
+**Correct - Provide ref immediately, update later:**
+```vue
+<script setup>
+import { provide, ref, onMounted } from 'vue'
+
+// Provide immediately with initial value
+const user = ref(null)
+const isLoading = ref(true)
+const error = ref(null)
+
+provide('userState', {
+  user,
+  isLoading,
+  error
+})
+
+// Update the ref values asynchronously
+onMounted(async () => {
+  try {
+    const userData = await fetchUser()
+    user.value = userData
+  } catch (e) {
+    error.value = e
+  } finally {
+    isLoading.value = false
+  }
+})
+</script>
+```
+
+```vue
+<!-- Consumer component -->
+<script setup>
+import { inject } from 'vue'
+
+const { user, isLoading, error } = inject('userState')
+</script>
+
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="error">Error: {{ error.message }}</div>
+  <div v-else>Welcome, {{ user?.name }}</div>
+</template>
+```
+
+## Pattern: Async Data Provider
+
+Create a reusable pattern for async-provided data:
+
+```vue
+<!-- AsyncDataProvider.vue -->
+<script setup>
+import { provide, ref, onMounted, watch } from 'vue'
+
+const props = defineProps({
+  fetchFn: {
+    type: Function,
+    required: true
+  },
+  provideKey: {
+    type: [String, Symbol],
+    required: true
+  },
+  immediate: {
+    type: Boolean,
+    default: true
+  }
+})
+
+const data = ref(null)
+const isLoading = ref(false)
+const error = ref(null)
+
+async function load() {
+  isLoading.value = true
+  error.value = null
+
+  try {
+    data.value = await props.fetchFn()
+  } catch (e) {
+    error.value = e
+  } finally {
+    isLoading.value = false
+  }
+}
+
+// Provide synchronously
+provide(props.provideKey, {
+  data,
+  isLoading,
+  error,
+  reload: load
+})
+
+// Fetch asynchronously
+if (props.immediate) {
+  onMounted(load)
+}
+</script>
+
+<template>
+  <slot />
+</template>
+```
+
+Usage:
+
+```vue
+<template>
+  <AsyncDataProvider
+    :fetch-fn="() => api.getUser(userId)"
+    provide-key="userData"
+  >
+    <UserProfile />
+  </AsyncDataProvider>
+</template>
+```
+
+## Why This Happens
+
+Vue's `provide()` relies on the current component instance context, which is only available synchronously during setup. After setup completes:
+
+1. The setup context is cleared
+2. `provide()` can't find the current instance
+3. The call fails silently (no error thrown)
+
+## Checking for Setup Context
+
+You can verify if setup context is available:
+
+```js
+import { getCurrentInstance } from 'vue'
+
+function debugProvide(key, value) {
+  const instance = getCurrentInstance()
+
+  if (!instance) {
+    console.error(
+      `provide() called outside setup context. ` +
+      `Key: ${String(key)}. This will fail silently.`
+    )
+    return
+  }
+
+  provide(key, value)
+}
+```
+
+## App-Level Provide (Exception)
+
+`app.provide()` can be called anytime during app initialization:
+
+```js
+// main.js
+import { createApp } from 'vue'
+import App from './App.vue'
+
+const app = createApp(App)
+
+// This works - app-level provide
+app.provide('appConfig', { version: '1.0.0' })
+
+// Even async is OK at app level before mount
+fetchConfig().then(config => {
+  app.provide('apiConfig', config)
+  app.mount('#app')
+})
+```
+
+But once the app is mounted, `app.provide()` should not be called.
+
+## Reference
+- [Vue.js Composition API - provide()](https://vuejs.org/api/composition-api-dependency-injection.html#provide)
+- [Vue.js Provide/Inject Guide](https://vuejs.org/guide/components/provide-inject.html)

package/skills/vue-debug-guides/reference/reactive-destructuring.md

@@ -0,0 +1,89 @@
+---
+title: Never Destructure reactive() Objects Directly
+impact: HIGH
+impactDescription: Destructuring reactive objects breaks reactivity - changes won't trigger updates
+type: capability
+tags: [vue3, reactivity, reactive, composition-api, destructuring]
+---
+
+# Never Destructure reactive() Objects Directly
+
+**Impact: HIGH** - Destructuring a `reactive()` object breaks the reactive connection. Updates to destructured variables won't trigger UI updates, leading to stale data display.
+
+Vue's `reactive()` uses JavaScript Proxies to track property access. When you destructure, you extract primitive values from the proxy, losing the reactive connection. This is especially dangerous when destructuring from composables or imported state.
+
+## Task Checklist
+
+- [ ] Never destructure reactive objects directly if you need reactivity
+- [ ] Use `toRefs()` to convert reactive object properties to refs before destructuring
+- [ ] Consider using `ref()` instead of `reactive()` to avoid this pitfall entirely
+- [ ] When importing state from composables, check if it's reactive before destructuring
+
+**Incorrect:**
+```javascript
+import { reactive } from 'vue'
+
+const state = reactive({
+  count: 0,
+  name: 'Vue'
+})
+
+// WRONG: Destructuring breaks reactivity
+const { count, name } = state
+
+// These updates work on the original state...
+state.count++  // state.count is now 1
+
+// ...but the destructured variables are NOT updated
+console.log(count)  // Still 0! Lost reactivity
+```
+
+```javascript
+// WRONG: Destructuring from a composable
+function useCounter() {
+  const state = reactive({ count: 0 })
+  return state
+}
+
+const { count } = useCounter()  // count is now a non-reactive primitive
+```
+
+**Correct:**
+```javascript
+import { reactive, toRefs } from 'vue'
+
+const state = reactive({
+  count: 0,
+  name: 'Vue'
+})
+
+// CORRECT: Use toRefs() to maintain reactivity
+const { count, name } = toRefs(state)
+
+state.count++
+console.log(count.value)  // 1 - Reactivity preserved! (note: now needs .value)
+```
+
+```javascript
+// CORRECT: Return toRefs from composables
+function useCounter() {
+  const state = reactive({ count: 0 })
+  return toRefs(state)  // Now safe to destructure
+}
+
+const { count } = useCounter()  // count is now a ref, reactivity preserved
+```
+
+```javascript
+// ALTERNATIVE: Just use ref() to avoid the issue entirely
+import { ref } from 'vue'
+
+const count = ref(0)
+const name = ref('Vue')
+
+// No destructuring needed, no gotchas
+```
+
+## Reference
+- [Vue.js Reactivity Fundamentals - reactive()](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#reactive)
+- [Vue.js Reactivity API - toRefs()](https://vuejs.org/api/reactivity-utilities.html#torefs)

package/skills/vue-debug-guides/reference/reactivity-debugging-hooks.md

@@ -0,0 +1,132 @@
+---
+title: Use Debug Hooks to Trace Reactivity Issues
+impact: MEDIUM
+impactDescription: Debug hooks help identify which dependencies trigger re-renders and watcher executions
+type: efficiency
+tags: [vue3, reactivity, debugging, computed, watch, development]
+---
+
+# Use Debug Hooks to Trace Reactivity Issues
+
+**Impact: MEDIUM** - Vue provides debug hooks (`onTrack`, `onTrigger`, `renderTracked`, `renderTriggered`) that help identify exactly which reactive dependencies are being tracked and which mutations trigger re-execution. These are invaluable for debugging performance issues and unexpected re-renders.
+
+Debug hooks only work in development mode and are stripped in production builds. Use them to understand why a computed property, watcher, or component is re-executing.
+
+## Task Checklist
+
+- [ ] Use `onTrack` and `onTrigger` options on computed/watch for granular debugging
+- [ ] Use `onRenderTracked` and `onRenderTriggered` lifecycle hooks for component render debugging
+- [ ] Add `debugger` statements inside hooks to pause execution and inspect state
+- [ ] Remove or comment out debug hooks before production (they're no-ops but add clutter)
+
+> **Note:** `onTrack` and `onTrigger` are development-only hooks. They are stripped from production builds and may not fire in test environments (e.g., Vitest, Jest) depending on how Vue is bundled. If you need to verify reactivity behavior in tests, use direct assertions on reactive state changes rather than relying on these debug callbacks.
+
+**Debugging computed properties:**
+```javascript
+import { ref, computed } from 'vue'
+
+const count = ref(0)
+const doubled = computed(() => count.value * 2, {
+  onTrack(event) {
+    // Called when a dependency is tracked
+    // event.target = the reactive object
+    // event.key = the property being accessed
+    debugger
+    console.log('Tracking:', event)
+  },
+  onTrigger(event) {
+    // Called when a dependency mutation triggers re-computation
+    debugger
+    console.log('Triggered by:', event)
+  }
+})
+```
+
+**Debugging watchers:**
+```javascript
+import { ref, watch, watchEffect } from 'vue'
+
+const source = ref(0)
+
+// With watch()
+watch(source, (newVal, oldVal) => {
+  console.log('Changed:', oldVal, '->', newVal)
+}, {
+  onTrack(e) {
+    debugger // Pause to see what's being tracked
+  },
+  onTrigger(e) {
+    debugger // Pause to see what triggered the watcher
+  }
+})
+
+// With watchEffect()
+watchEffect(() => {
+  console.log('Source is:', source.value)
+}, {
+  onTrack(e) {
+    console.log('Tracking dependency:', e.key)
+  },
+  onTrigger(e) {
+    console.log('Triggered by:', e.key, 'mutation')
+  }
+})
+```
+
+**Debugging component renders:**
+```vue
+<script setup>
+import { onRenderTracked, onRenderTriggered, ref } from 'vue'
+
+const count = ref(0)
+
+// Called for every reactive dependency accessed during render
+onRenderTracked((event) => {
+  console.log('Render tracked:', event.key, 'from', event.target)
+  debugger // Pause to inspect which dependencies are tracked
+})
+
+// Called when a reactive dependency triggers re-render
+onRenderTriggered((event) => {
+  console.log('Render triggered by:', event.key)
+  console.log('Old value:', event.oldValue)
+  console.log('New value:', event.newValue)
+  debugger // Pause to see exactly what caused the re-render
+})
+</script>
+```
+
+**Options API equivalent:**
+```javascript
+export default {
+  data() {
+    return { count: 0 }
+  },
+  renderTracked(event) {
+    console.log('Dependency tracked during render:', event)
+    debugger
+  },
+  renderTriggered(event) {
+    console.log('Re-render triggered by:', event)
+    debugger
+  }
+}
+```
+
+**Debug event properties:**
+```javascript
+// The event object contains:
+{
+  effect: ReactiveEffect,  // The effect being debugged
+  target: object,          // The reactive object
+  type: 'get' | 'set' | 'add' | 'delete' | 'clear',
+  key: string | symbol,    // The property being accessed/mutated
+  oldValue: any,           // Previous value (for onTrigger)
+  newValue: any            // New value (for onTrigger)
+}
+```
+
+## Reference
+- [Vue.js Reactivity in Depth - Debugging](https://vuejs.org/guide/extras/reactivity-in-depth.html#reactivity-debugging)
+- [Vue.js computed() API](https://vuejs.org/api/reactivity-core.html#computed)
+- [Vue.js onRenderTracked()](https://vuejs.org/api/composition-api-lifecycle.html#onrendertracked)

package/skills/vue-debug-guides/reference/reactivity-markraw-for-non-reactive.md

@@ -0,0 +1,149 @@
+---
+title: Use markRaw() for Objects That Should Never Be Reactive
+impact: MEDIUM
+impactDescription: Library instances, DOM nodes, and complex objects cause overhead and bugs when wrapped in Vue proxies
+type: efficiency
+tags: [vue3, reactivity, markRaw, performance, external-libraries, dom]
+---
+
+# Use markRaw() for Objects That Should Never Be Reactive
+
+**Impact: MEDIUM** - Vue's `markRaw()` tells the reactivity system to never wrap an object in a Proxy. Use it for library instances, DOM nodes, class instances with internal state, and complex objects that Vue shouldn't track. This prevents unnecessary proxy overhead and avoids subtle bugs from double-proxying.
+
+Without `markRaw()`, placing these objects inside reactive state causes Vue to wrap them in Proxies, which can break library internals, cause identity issues, and waste memory on objects that don't need change tracking.
+
+## Task Checklist
+
+- [ ] Use `markRaw()` for third-party library instances (maps, charts, editors)
+- [ ] Use `markRaw()` for DOM elements stored in reactive state
+- [ ] Use `markRaw()` for class instances that manage their own state
+- [ ] Use `markRaw()` for large static data that will never change
+- [ ] Remember: markRaw only affects the root level - nested objects may still be proxied
+
+**Incorrect:**
+```javascript
+import { reactive, ref } from 'vue'
+import mapboxgl from 'mapbox-gl'
+import * as monaco from 'monaco-editor'
+
+// WRONG: Library instances wrapped in Proxy
+const state = reactive({
+  map: new mapboxgl.Map({ container: 'map' }),  // Proxied!
+  editor: monaco.editor.create(element, {}),    // Proxied!
+})
+
+// Problems:
+// 1. Library's internal this references may break
+// 2. Unnecessary memory overhead
+// 3. Methods may not work correctly through proxy
+// 4. Performance degradation
+
+// WRONG: DOM elements in reactive state
+const elements = reactive({
+  container: document.getElementById('app'),  // Proxied DOM node!
+})
+```
+
+**Correct:**
+```javascript
+import { reactive, markRaw, shallowRef } from 'vue'
+import mapboxgl from 'mapbox-gl'
+import * as monaco from 'monaco-editor'
+
+// CORRECT: Mark library instances as raw
+const state = reactive({
+  map: markRaw(new mapboxgl.Map({ container: 'map' })),
+  editor: markRaw(monaco.editor.create(element, {})),
+})
+
+// CORRECT: Or use shallowRef for mutable references
+const map = shallowRef(null)
+onMounted(() => {
+  map.value = markRaw(new mapboxgl.Map({ container: 'map' }))
+})
+
+// CORRECT: Large static data
+const geoJsonData = markRaw(await fetch('/huge-geojson.json').then(r => r.json()))
+const state = reactive({
+  mapData: geoJsonData  // Won't be proxied
+})
+```
+
+**Class instances with internal state:**
+```javascript
+import { markRaw, reactive } from 'vue'
+
+class WebSocketManager {
+  constructor(url) {
+    this.socket = new WebSocket(url)
+    this.listeners = new Map()
+  }
+
+  on(event, callback) {
+    this.listeners.set(event, callback)
+  }
+}
+
+// CORRECT: Mark class instance
+const wsManager = markRaw(new WebSocketManager('ws://example.com'))
+
+const state = reactive({
+  connection: wsManager  // Won't be proxied
+})
+
+// Can still use the instance normally
+state.connection.on('message', handleMessage)
+```
+
+**Gotcha: markRaw only affects root level:**
+```javascript
+import { markRaw, reactive } from 'vue'
+
+const rawObject = markRaw({
+  nested: { value: 1 }  // This nested object is NOT marked raw
+})
+
+const state = reactive({
+  data: rawObject
+})
+
+// rawObject itself won't be proxied
+// But if you access nested objects through a reactive parent:
+const container = reactive({ raw: rawObject })
+// container.raw.nested might still be proxied in some cases
+
+// SAFER: Use shallowRef for the container
+import { shallowRef } from 'vue'
+const safeContainer = shallowRef(rawObject)
+```
+
+**Combining with shallowRef for best results:**
+```javascript
+import { shallowRef, markRaw, onMounted, onUnmounted } from 'vue'
+
+// Pattern: shallowRef + markRaw for external library instances
+export function useMapbox(containerId) {
+  const map = shallowRef(null)
+
+  onMounted(() => {
+    const instance = new mapboxgl.Map({
+      container: containerId,
+      style: 'mapbox://styles/mapbox/streets-v11'
+    })
+
+    // Mark raw to prevent any proxy wrapping
+    map.value = markRaw(instance)
+  })
+
+  onUnmounted(() => {
+    map.value?.remove()
+  })
+
+  return { map }
+}
+```
+
+## Reference
+- [Vue.js markRaw() API](https://vuejs.org/api/reactivity-advanced.html#markraw)
+- [Vue.js Reducing Reactivity Overhead](https://vuejs.org/guide/best-practices/performance.html#reduce-reactivity-overhead-for-large-immutable-structures)
+- [Vue.js Reactivity in Depth](https://vuejs.org/guide/extras/reactivity-in-depth.html)

package/skills/vue-debug-guides/reference/reactivity-proxy-identity-hazard.md

@@ -0,0 +1,96 @@
+---
+title: Avoid Comparing Reactive Objects with === Operator
+impact: HIGH
+impactDescription: Reactive proxies have different identity than original objects - comparison bugs are silent and hard to debug
+type: gotcha
+tags: [vue3, reactivity, proxy, comparison, debugging, identity]
+---
+
+# Avoid Comparing Reactive Objects with === Operator
+
+**Impact: HIGH** - Vue's `reactive()` returns a Proxy wrapper that has a different identity than the original object. Using `===` to compare reactive objects can lead to silent bugs where comparisons unexpectedly return `false`.
+
+When you wrap an object with `reactive()`, the returned proxy is NOT equal to the original object. Additionally, accessing nested objects from a reactive object returns new proxy wrappers each time, which can cause identity comparison issues.
+
+## Task Checklist
+
+- [ ] Never compare reactive object instances with `===` directly
+- [ ] Use unique identifiers (ID, UUID) for object comparison instead
+- [ ] Use `toRaw()` on both sides when identity comparison is absolutely necessary
+- [ ] Consider using primitive identifiers from database records for comparison
+
+**Incorrect:**
+```javascript
+import { reactive } from 'vue'
+
+const original = { id: 1, name: 'Item' }
+const state = reactive(original)
+
+// BUG: Always returns false - proxy !== original
+if (state === original) {
+  console.log('Same object') // Never executes
+}
+
+// BUG: Nested object comparison fails
+const items = reactive([{ id: 1 }, { id: 2 }])
+const item = items[0]
+
+// Later...
+if (items[0] === item) {
+  // May or may not work depending on Vue's proxy caching
+}
+
+// BUG: Comparing items from different reactive sources
+const listA = reactive([{ id: 1 }])
+const listB = reactive([{ id: 1 }])
+if (listA[0] === listB[0]) {
+  // Never true, even though they represent the same data
+}
+```
+
+**Correct:**
+```javascript
+import { reactive, toRaw } from 'vue'
+
+const original = { id: 1, name: 'Item' }
+const state = reactive(original)
+
+// CORRECT: Use toRaw() for identity comparison
+if (toRaw(state) === original) {
+  console.log('Same underlying object') // Works!
+}
+
+// BEST: Use unique identifiers instead
+const items = reactive([
+  { id: 'uuid-1', name: 'Item 1' },
+  { id: 'uuid-2', name: 'Item 2' }
+])
+
+function findItem(targetId) {
+  return items.find(item => item.id === targetId)
+}
+
+function isSelected(item) {
+  return selectedId.value === item.id // Compare IDs, not objects
+}
+
+// CORRECT: For Set/Map operations, use primitive keys
+const selectedIds = reactive(new Set())
+selectedIds.add(item.id)  // Use ID, not object
+selectedIds.has(item.id)  // Check by ID
+```
+
+```javascript
+// When you must compare objects, use toRaw on both sides
+import { toRaw, isReactive } from 'vue'
+
+function areEqual(a, b) {
+  const rawA = isReactive(a) ? toRaw(a) : a
+  const rawB = isReactive(b) ? toRaw(b) : b
+  return rawA === rawB
+}
+```
+
+## Reference
+- [Vue.js Reactivity in Depth](https://vuejs.org/guide/extras/reactivity-in-depth.html)
+- [Vue.js toRaw() API](https://vuejs.org/api/reactivity-advanced.html#toraw)