@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/watch-deep-same-object-reference.md

@@ -0,0 +1,165 @@
+---
+title: Deep Watch Callback Receives Same Object Reference for Old and New Values
+impact: MEDIUM
+impactDescription: Comparing oldValue and newValue in deep watchers is misleading since they reference the same object
+type: capability
+tags: [vue3, watch, watchers, deep, oldValue, newValue, object-reference]
+---
+
+# Deep Watch Callback Receives Same Object Reference for Old and New Values
+
+**Impact: MEDIUM** - When using deep watchers on reactive objects, both `newValue` and `oldValue` in the callback point to the same object reference. They will always be equal for nested mutations because Vue doesn't clone the object before mutation.
+
+Don't rely on comparing `newValue` to `oldValue` in deep watchers for detecting what changed. Instead, track specific values or implement your own diffing.
+
+## Task Checklist
+
+- [ ] Don't compare newValue === oldValue in deep watchers to detect changes
+- [ ] For change detection, watch specific properties instead
+- [ ] If you need old values, manually snapshot before changes
+- [ ] Consider using a serialization approach for complex diffing needs
+- [ ] The values differ only when the entire object is replaced
+
+**Incorrect:**
+```javascript
+import { reactive, watch } from 'vue'
+
+const state = reactive({
+  user: {
+    name: 'John',
+    preferences: { theme: 'dark' }
+  }
+})
+
+// BAD: Trying to compare old and new values
+watch(
+  () => state.user,
+  (newUser, oldUser) => {
+    // This comparison is ALWAYS true for nested mutations!
+    if (newUser === oldUser) {
+      console.log('Same reference!')  // Always logs for nested changes
+    }
+
+    // This also won't work - they're the same object
+    if (newUser.name !== oldUser.name) {
+      console.log('Name changed')  // Never logs for nested mutations
+    }
+  },
+  { deep: true }
+)
+
+// When this happens:
+state.user.name = 'Jane'
+// Both newUser and oldUser are { name: 'Jane', preferences: { theme: 'dark' } }
+```
+
+**Correct:**
+```javascript
+import { reactive, watch, ref } from 'vue'
+
+const state = reactive({
+  user: {
+    name: 'John',
+    preferences: { theme: 'dark' }
+  }
+})
+
+// CORRECT: Watch specific properties you care about
+watch(
+  () => state.user.name,
+  (newName, oldName) => {
+    console.log(`Name changed from "${oldName}" to "${newName}"`)
+    // oldName and newName are primitives, work correctly
+  }
+)
+
+// CORRECT: Watch multiple specific properties
+watch(
+  [() => state.user.name, () => state.user.preferences.theme],
+  ([newName, newTheme], [oldName, oldTheme]) => {
+    if (newName !== oldName) {
+      console.log(`Name: ${oldName} -> ${newName}`)
+    }
+    if (newTheme !== oldTheme) {
+      console.log(`Theme: ${oldTheme} -> ${newTheme}`)
+    }
+  }
+)
+```
+
+## Manual Snapshot Pattern
+
+```javascript
+import { reactive, watch, ref } from 'vue'
+
+const state = reactive({ count: 0, items: [] })
+
+// Keep a manual snapshot for comparison
+const previousSnapshot = ref(JSON.stringify(state))
+
+watch(
+  state,
+  (newState) => {
+    const currentSnapshot = JSON.stringify(newState)
+
+    if (currentSnapshot !== previousSnapshot.value) {
+      const oldData = JSON.parse(previousSnapshot.value)
+      console.log('Old:', oldData)
+      console.log('New:', newState)
+
+      // Update snapshot for next comparison
+      previousSnapshot.value = currentSnapshot
+    }
+  },
+  { deep: true }
+)
+```
+
+## When Old and New Values Differ
+
+```javascript
+import { reactive, watch } from 'vue'
+
+const state = reactive({
+  currentUser: { name: 'John' }
+})
+
+watch(
+  () => state.currentUser,
+  (newUser, oldUser) => {
+    // THESE DIFFER when the object itself is replaced
+    console.log('Old:', oldUser)  // { name: 'John' }
+    console.log('New:', newUser)  // { name: 'Jane' }
+  },
+  { deep: true }
+)
+
+// Object replacement - old and new are different
+state.currentUser = { name: 'Jane' }
+
+// vs. Mutation - old and new are the same reference
+// state.currentUser.name = 'Jane'
+```
+
+## Using Getter Returns New Object
+
+```javascript
+import { reactive, watch } from 'vue'
+
+const state = reactive({
+  user: { firstName: 'John', lastName: 'Doe' }
+})
+
+// CORRECT: Getter returns new object, so old/new comparison works
+watch(
+  () => ({ ...state.user }),  // Shallow clone
+  (newUser, oldUser) => {
+    // Now these are different objects
+    console.log('Changed from', oldUser, 'to', newUser)
+  },
+  { deep: true }
+)
+```
+
+## Reference
+- [Vue.js Watchers - Deep Watchers](https://vuejs.org/guide/essentials/watchers.html#deep-watchers)

package/skills/vue-debug-guides/reference/watch-flush-timing.md

@@ -0,0 +1,189 @@
+---
+title: Use flush post When Accessing Updated DOM in Watchers
+impact: MEDIUM
+impactDescription: Default watcher timing runs before DOM updates, causing stale DOM reads
+type: capability
+tags: [vue3, watch, watchers, flush, DOM, timing, post]
+---
+
+# Use flush: 'post' When Accessing Updated DOM in Watchers
+
+**Impact: MEDIUM** - By default, watcher callbacks run before the component's DOM is updated. If you access the DOM in a watcher callback, you'll see the pre-update state. Use `flush: 'post'` or `watchPostEffect` when you need to access the updated DOM.
+
+## Task Checklist
+
+- [ ] Use `{ flush: 'post' }` when reading DOM after reactive state changes
+- [ ] Use `watchPostEffect()` as a shorthand for `watchEffect` with flush: 'post'
+- [ ] Avoid `{ flush: 'sync' }` unless absolutely necessary (performance impact)
+- [ ] Remember default timing is ideal for most non-DOM operations
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, watch, watchEffect } from 'vue'
+
+const count = ref(0)
+const listItems = ref(['a', 'b', 'c'])
+
+// BAD: DOM shows old value when this runs
+watch(count, () => {
+  // Element still shows the OLD count value
+  const el = document.querySelector('.counter')
+  console.log('DOM shows:', el.textContent)  // Old value!
+})
+
+// BAD: List DOM not yet updated
+watchEffect(() => {
+  console.log('Items:', listItems.value.length)
+  // DOM still has old number of list items
+  const items = document.querySelectorAll('.list-item')
+  console.log('DOM items:', items.length)  // Old count!
+})
+</script>
+
+<template>
+  <div class="counter">{{ count }}</div>
+  <ul>
+    <li v-for="item in listItems" :key="item" class="list-item">
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, watch, watchEffect, watchPostEffect } from 'vue'
+
+const count = ref(0)
+const listItems = ref(['a', 'b', 'c'])
+
+// CORRECT: flush: 'post' runs after DOM update
+watch(
+  count,
+  () => {
+    const el = document.querySelector('.counter')
+    console.log('DOM shows:', el.textContent)  // Correct new value!
+  },
+  { flush: 'post' }
+)
+
+// CORRECT: watchPostEffect shorthand
+watchPostEffect(() => {
+  console.log('Items:', listItems.value.length)
+  const items = document.querySelectorAll('.list-item')
+  console.log('DOM items:', items.length)  // Matches listItems.length!
+})
+
+// CORRECT: Using watchEffect with flush option
+watchEffect(
+  () => {
+    // Access reactive state and DOM together
+    const expectedCount = listItems.value.length
+    const actualCount = document.querySelectorAll('.list-item').length
+    console.log(`Expected: ${expectedCount}, Actual: ${actualCount}`)
+  },
+  { flush: 'post' }
+)
+</script>
+
+<template>
+  <div class="counter">{{ count }}</div>
+  <ul>
+    <li v-for="item in listItems" :key="item" class="list-item">
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+## Flush Timing Options
+
+```javascript
+import { watch, watchEffect, watchPostEffect, watchSyncEffect } from 'vue'
+
+// Default: 'pre' - runs before component DOM update
+watch(source, callback)  // Same as { flush: 'pre' }
+
+// Post: runs after component DOM update
+watch(source, callback, { flush: 'post' })
+watchPostEffect(callback)  // Shorthand
+
+// Sync: runs immediately when reactive value changes
+// USE WITH CAUTION - no batching, fires on every mutation
+watch(source, callback, { flush: 'sync' })
+watchSyncEffect(callback)  // Shorthand
+```
+
+## When to Use Each Flush Timing
+
+| Timing | Use Case |
+|--------|----------|
+| `'pre'` (default) | Logic that doesn't need DOM access |
+| `'post'` | Reading or measuring updated DOM |
+| `'sync'` | Debug logging, simple boolean flags only |
+
+## Sync Watcher Warning
+
+```javascript
+import { ref, watch } from 'vue'
+
+const items = ref([1, 2, 3])
+
+// DANGEROUS: Fires for EVERY array mutation
+watch(
+  items,
+  () => {
+    console.log('Changed!')  // Called 3 times for push, push, push
+  },
+  { flush: 'sync' }
+)
+
+// This triggers the watcher 3 times synchronously
+items.value.push(4)
+items.value.push(5)
+items.value.push(6)
+
+// Better: Use default flush which batches updates
+watch(items, () => {
+  console.log('Changed!')  // Called once after all mutations
+}, { deep: true })
+```
+
+## Practical Example: Auto-scroll
+
+```vue
+<script setup>
+import { ref, watchPostEffect } from 'vue'
+
+const messages = ref([])
+const containerRef = ref(null)
+
+// Auto-scroll to bottom when new messages arrive
+watchPostEffect(() => {
+  // Access messages.value to track it
+  const msgCount = messages.value.length
+
+  // DOM is updated, safe to scroll
+  if (containerRef.value && msgCount > 0) {
+    containerRef.value.scrollTop = containerRef.value.scrollHeight
+  }
+})
+
+function addMessage(text) {
+  messages.value.push({ text, timestamp: Date.now() })
+}
+</script>
+
+<template>
+  <div ref="containerRef" class="messages">
+    <div v-for="msg in messages" :key="msg.timestamp">
+      {{ msg.text }}
+    </div>
+  </div>
+</template>
+```
+
+## Reference
+- [Vue.js Watchers - Callback Flush Timing](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing)

package/skills/vue-debug-guides/reference/watch-reactive-property-getter.md

@@ -0,0 +1,108 @@
+---
+title: Use Getter Function When Watching Reactive Object Properties
+impact: HIGH
+impactDescription: Watching reactive properties directly passes a primitive value, causing the watcher to never trigger
+type: capability
+tags: [vue3, watch, watchers, reactive, getter, common-mistake]
+---
+
+# Use Getter Function When Watching Reactive Object Properties
+
+**Impact: HIGH** - Directly watching a property of a reactive object passes a primitive value to `watch()`, not a reactive reference. The watcher will never trigger because primitives are not reactive.
+
+When you need to watch a specific property of a reactive object, always wrap it in a getter function `() => obj.property`.
+
+## Task Checklist
+
+- [ ] Always use getter functions when watching properties of reactive objects
+- [ ] Remember that `watch(obj.count, ...)` passes the current value, not a reactive reference
+- [ ] For refs, you can watch directly: `watch(myRef, ...)`
+- [ ] For entire reactive objects, you can watch directly (creates implicit deep watcher)
+
+**Incorrect:**
+```javascript
+import { reactive, watch } from 'vue'
+
+const state = reactive({ count: 0, name: 'Vue' })
+
+// WRONG: Passes the number 0 to watch(), not a reactive reference
+// This watcher will NEVER fire!
+watch(state.count, (newCount) => {
+  console.log(`Count changed to: ${newCount}`)
+})
+
+// WRONG: Same problem with string property
+watch(state.name, (newName) => {
+  console.log(`Name changed to: ${newName}`)
+})
+```
+
+**Correct:**
+```javascript
+import { reactive, watch } from 'vue'
+
+const state = reactive({ count: 0, name: 'Vue' })
+
+// CORRECT: Use a getter function
+watch(
+  () => state.count,
+  (newCount, oldCount) => {
+    console.log(`Count changed from ${oldCount} to ${newCount}`)
+  }
+)
+
+// CORRECT: Multiple properties with getter
+watch(
+  () => state.name,
+  (newName) => {
+    console.log(`Name changed to: ${newName}`)
+  }
+)
+
+// CORRECT: Watching derived values
+watch(
+  () => state.count * 2,
+  (doubledCount) => {
+    console.log(`Doubled count: ${doubledCount}`)
+  }
+)
+```
+
+## Watching Multiple Properties
+
+```javascript
+import { reactive, watch } from 'vue'
+
+const state = reactive({ firstName: 'John', lastName: 'Doe' })
+
+// Watch multiple properties with array of getters
+watch(
+  [() => state.firstName, () => state.lastName],
+  ([newFirst, newLast], [oldFirst, oldLast]) => {
+    console.log(`Name changed from ${oldFirst} ${oldLast} to ${newFirst} ${newLast}`)
+  }
+)
+```
+
+## When Direct Watching Works
+
+```javascript
+import { ref, reactive, watch } from 'vue'
+
+const count = ref(0)
+const state = reactive({ nested: { value: 1 } })
+
+// CORRECT: Refs can be watched directly
+watch(count, (newVal) => {
+  console.log(`Count: ${newVal}`)
+})
+
+// CORRECT: Entire reactive objects create implicit deep watcher
+watch(state, (newState) => {
+  // Fires on any nested change
+  // Note: newState === oldState (same object reference)
+})
+```
+
+## Reference
+- [Vue.js Watchers - Watch Source Types](https://vuejs.org/guide/essentials/watchers.html#watch-source-types)

package/skills/vue-debug-guides/reference/watcheffect-async-dependency-tracking.md

@@ -0,0 +1,173 @@
+---
+title: watchEffect Only Tracks Dependencies Before First Await
+impact: HIGH
+impactDescription: Dependencies accessed after await are not tracked, causing watchers to miss reactive changes
+type: capability
+tags: [vue3, watchEffect, watchers, async, await, dependency-tracking]
+---
+
+# watchEffect Only Tracks Dependencies Before First Await
+
+**Impact: HIGH** - `watchEffect` automatically tracks reactive dependencies, but only during synchronous execution. Any reactive properties accessed after the first `await` statement will NOT be tracked, and changes to them won't trigger the watcher.
+
+For async operations, either access all dependencies before the await, or use `watch` with explicit dependencies.
+
+## Task Checklist
+
+- [ ] Access all reactive dependencies BEFORE the first await in watchEffect
+- [ ] Use `watch` with explicit source when async tracking is needed
+- [ ] Store reactive values in local variables before await
+- [ ] Be aware that dependencies after await are invisible to Vue
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, watchEffect } from 'vue'
+
+const userId = ref(1)
+const includeDetails = ref(true)
+const userData = ref(null)
+
+// BAD: includeDetails is accessed after await - NOT TRACKED!
+watchEffect(async () => {
+  const response = await fetch(`/api/users/${userId.value}`)
+  const data = await response.json()
+
+  // This dependency is NOT tracked - changes won't trigger re-run
+  if (includeDetails.value) {
+    userData.value = { ...data, details: await fetchDetails(data.id) }
+  } else {
+    userData.value = data
+  }
+})
+
+// BAD: Multiple dependencies after await
+watchEffect(async () => {
+  await someAsyncSetup()
+
+  // None of these are tracked!
+  console.log(optionA.value)  // Not tracked
+  console.log(optionB.value)  // Not tracked
+  doSomething(optionC.value)  // Not tracked
+})
+</script>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, watchEffect, watch } from 'vue'
+
+const userId = ref(1)
+const includeDetails = ref(true)
+const userData = ref(null)
+
+// CORRECT: Access all dependencies before await
+watchEffect(async () => {
+  // Capture reactive values synchronously
+  const id = userId.value
+  const withDetails = includeDetails.value
+
+  // Now these are tracked
+  const response = await fetch(`/api/users/${id}`)
+  const data = await response.json()
+
+  if (withDetails) {
+    userData.value = { ...data, details: await fetchDetails(data.id) }
+  } else {
+    userData.value = data
+  }
+})
+
+// ALTERNATIVE: Use watch with explicit dependencies
+watch(
+  [userId, includeDetails],
+  async ([id, withDetails]) => {
+    const response = await fetch(`/api/users/${id}`)
+    const data = await response.json()
+
+    if (withDetails) {
+      userData.value = { ...data, details: await fetchDetails(data.id) }
+    } else {
+      userData.value = data
+    }
+  },
+  { immediate: true }
+)
+</script>
+```
+
+## Pattern: Extract Dependencies First
+
+```vue
+<script setup>
+import { ref, watchEffect } from 'vue'
+
+const filters = ref({ status: 'active', sortBy: 'name' })
+const page = ref(1)
+const results = ref([])
+
+// CORRECT: Extract all needed values synchronously
+watchEffect(async () => {
+  // All dependencies accessed before await - all tracked!
+  const { status, sortBy } = filters.value
+  const currentPage = page.value
+
+  // Now safe to do async work
+  const response = await fetch(
+    `/api/items?status=${status}&sort=${sortBy}&page=${currentPage}`
+  )
+  results.value = await response.json()
+})
+</script>
+```
+
+## When to Use watch Instead
+
+```vue
+<script setup>
+import { ref, watch } from 'vue'
+
+const source = ref('initial')
+const option = ref('default')
+const result = ref(null)
+
+// BEST for complex async: Use watch with explicit sources
+// All dependencies are explicitly declared and always tracked
+watch(
+  [source, option],
+  async ([sourceVal, optionVal]) => {
+    const data = await processAsync(sourceVal)
+    result.value = applyOption(data, optionVal)
+  },
+  { immediate: true }
+)
+</script>
+```
+
+## Debugging Untracked Dependencies
+
+```vue
+<script setup>
+import { ref, watchEffect } from 'vue'
+
+const a = ref(1)
+const b = ref(2)
+
+watchEffect(async () => {
+  console.log('Tracked dependency a:', a.value)  // Tracked
+
+  await someAsyncOperation()
+
+  console.log('Untracked dependency b:', b.value)  // NOT tracked!
+  // Changing b.value won't re-run this watchEffect
+})
+
+// Test: Change a.value -> watchEffect re-runs
+// Test: Change b.value -> watchEffect does NOT re-run
+</script>
+```
+
+## Reference
+- [Vue.js Watchers - watchEffect](https://vuejs.org/guide/essentials/watchers.html#watcheffect)
+- [Vue.js API - watchEffect](https://vuejs.org/api/reactivity-core.html#watcheffect)