@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/composable-tovalue-inside-watcheffect.md

@@ -0,0 +1,182 @@
+---
+title: Call toValue() Inside watchEffect for Proper Dependency Tracking
+impact: HIGH
+impactDescription: Calling toValue() outside watchEffect prevents reactive dependency tracking, causing the effect to never re-run
+type: gotcha
+tags: [vue3, composables, composition-api, watchEffect, toValue, reactivity]
+---
+
+# Call toValue() Inside watchEffect for Proper Dependency Tracking
+
+**Impact: HIGH** - When writing composables that accept `MaybeRefOrGetter` arguments, you must call `toValue()` inside the `watchEffect` callback, not outside. If you extract the value before the watchEffect, Vue cannot track the dependency and the effect will never re-run when the source changes.
+
+This is a subtle but critical mistake that leads to composables that work with initial values but never update.
+
+## Task Checklist
+
+- [ ] Always call `toValue()` inside `watchEffect` callbacks, not before
+- [ ] Similarly, access `.value` on refs inside watchEffect, not outside
+- [ ] For `watch()`, use a getter function that calls `toValue()`
+- [ ] Test that composables update when their inputs change
+
+**Incorrect:**
+```javascript
+import { ref, watchEffect, toValue } from 'vue'
+
+export function useFetch(url) {
+  const data = ref(null)
+  const error = ref(null)
+
+  // WRONG: toValue called outside watchEffect
+  // This extracts the value ONCE and passes a static string
+  const urlValue = toValue(url)
+
+  watchEffect(async () => {
+    try {
+      // urlValue is a static string - no dependency tracked!
+      const response = await fetch(urlValue)
+      data.value = await response.json()
+    } catch (e) {
+      error.value = e
+    }
+  })
+
+  return { data, error }
+}
+
+// When used like this:
+const apiUrl = ref('/api/users')
+const { data } = useFetch(apiUrl)
+
+// Later...
+apiUrl.value = '/api/products'  // useFetch will NOT refetch!
+```
+
+**Correct:**
+```javascript
+import { ref, watchEffect, toValue } from 'vue'
+
+export function useFetch(url) {
+  const data = ref(null)
+  const error = ref(null)
+
+  watchEffect(async () => {
+    // CORRECT: toValue called INSIDE watchEffect
+    // Vue tracks this as a dependency
+    const urlValue = toValue(url)
+
+    try {
+      const response = await fetch(urlValue)
+      data.value = await response.json()
+    } catch (e) {
+      error.value = e
+    }
+  })
+
+  return { data, error }
+}
+
+// Now when used:
+const apiUrl = ref('/api/users')
+const { data } = useFetch(apiUrl)
+
+// Later...
+apiUrl.value = '/api/products'  // useFetch WILL refetch!
+```
+
+## The Same Applies to Direct Ref Access
+
+```javascript
+// WRONG: Accessing .value outside the effect
+export function useDebounce(source, delay = 300) {
+  // This captures the initial value, not a reactive dependency
+  const initialValue = source.value  // or toValue(source)
+
+  watchEffect(() => {
+    // initialValue is static - this only runs once
+    console.log('Value:', initialValue)
+  })
+}
+
+// CORRECT: Access inside the effect
+export function useDebounce(source, delay = 300) {
+  watchEffect(() => {
+    // Vue tracks source.value or toValue(source) as dependency
+    console.log('Value:', toValue(source))
+  })
+}
+```
+
+## Pattern: Using watch() with Getter Functions
+
+For `watch()`, wrap `toValue()` in a getter:
+
+```javascript
+import { ref, watch, toValue } from 'vue'
+
+export function useLocalStorage(key, defaultValue) {
+  const data = ref(defaultValue)
+
+  // CORRECT: Use getter function with watch
+  watch(
+    () => toValue(key),  // Getter calls toValue, tracks dependency
+    (newKey) => {
+      const stored = localStorage.getItem(newKey)
+      data.value = stored ? JSON.parse(stored) : defaultValue
+    },
+    { immediate: true }
+  )
+
+  return data
+}
+```
+
+## Why This Happens
+
+Vue's reactivity tracking works by detecting property accesses during effect execution:
+
+```javascript
+watchEffect(() => {
+  // When this runs, Vue is "recording" what reactive sources are accessed
+  const value = someRef.value  // Vue records: "this effect depends on someRef"
+})
+
+// But if you extract the value before:
+const value = someRef.value  // Vue isn't recording yet
+watchEffect(() => {
+  console.log(value)  // Just using a plain JavaScript variable
+})
+```
+
+`toValue()` works the same way - it accesses `.value` internally, so it must happen during effect execution for tracking to work.
+
+## Quick Checklist for Composable Authors
+
+When accepting `MaybeRefOrGetter` inputs:
+
+1. Store the raw argument (don't call `toValue` during setup)
+2. Call `toValue()` inside any reactive context (`watchEffect`, `watch`, `computed`)
+3. Test with both static values AND refs that change
+
+```javascript
+export function useMyComposable(input) {
+  // Store raw - don't extract value here
+  // const value = toValue(input)  // WRONG
+
+  const result = computed(() => {
+    // Extract value inside reactive context
+    return transform(toValue(input))  // CORRECT
+  })
+
+  watchEffect(() => {
+    // Extract value inside reactive context
+    doSomething(toValue(input))  // CORRECT
+  })
+
+  return { result }
+}
+```
+
+## Reference
+- [Vue.js Reactivity API - toValue](https://vuejs.org/api/reactivity-utilities.html#tovalue)
+- [Vue.js Composables - Accepting Ref Arguments](https://vuejs.org/guide/reusability/composables.html#accepting-reactive-state)

package/skills/vue-debug-guides/reference/composition-api-not-functional-programming.md

@@ -0,0 +1,120 @@
+---
+title: Composition API Uses Mutable Reactivity, Not Functional Programming
+impact: MEDIUM
+impactDescription: Misunderstanding the paradigm leads to incorrect state management patterns
+type: gotcha
+tags: [vue3, composition-api, reactivity, functional-programming, paradigm]
+---
+
+# Composition API Uses Mutable Reactivity, Not Functional Programming
+
+**Impact: MEDIUM** - Despite being function-based, the Composition API follows Vue's mutable, fine-grained reactivity paradigm—NOT functional programming principles. Treating it like a functional paradigm leads to incorrect patterns like unnecessary cloning, immutable-style updates, or avoiding mutation when mutation is the intended pattern.
+
+Vue's Composition API leverages imported functions to organize code, but the underlying model is based on mutable reactive state that Vue tracks and responds to. This is fundamentally different from functional programming with immutability (like Redux reducers).
+
+## Task Checklist
+
+- [ ] Mutate reactive state directly - don't create new objects for every update
+- [ ] Don't apply immutability patterns unnecessarily (spreading, Object.assign for updates)
+- [ ] Understand that `ref()` and `reactive()` enable mutable state tracking
+- [ ] Use Vue's reactivity as intended: direct mutation with automatic tracking
+
+**Incorrect:**
+```javascript
+import { ref } from 'vue'
+
+const todos = ref([])
+
+// WRONG: Treating Vue like Redux/functional - unnecessary immutability
+function addTodo(todo) {
+  // Creating a new array every time is wasteful in Vue
+  todos.value = [...todos.value, todo]
+}
+
+function updateTodo(id, updates) {
+  // Unnecessary spread - Vue tracks mutations directly
+  todos.value = todos.value.map(t =>
+    t.id === id ? { ...t, ...updates } : t
+  )
+}
+
+const user = ref({ name: 'John', age: 30 })
+
+// WRONG: Creating new object for simple update
+function updateName(newName) {
+  user.value = { ...user.value, name: newName }
+}
+```
+
+**Correct:**
+```javascript
+import { ref, reactive } from 'vue'
+
+const todos = ref([])
+
+// CORRECT: Mutate directly - Vue tracks the change
+function addTodo(todo) {
+  todos.value.push(todo)  // Direct mutation is the Vue way
+}
+
+function updateTodo(id, updates) {
+  const todo = todos.value.find(t => t.id === id)
+  if (todo) {
+    Object.assign(todo, updates)  // Direct mutation
+  }
+}
+
+const user = ref({ name: 'John', age: 30 })
+
+// CORRECT: Mutate the property directly
+function updateName(newName) {
+  user.value.name = newName  // Vue tracks this!
+}
+
+// Or with reactive():
+const state = reactive({ name: 'John', age: 30 })
+
+function updateNameReactive(newName) {
+  state.name = newName  // Direct mutation, reactivity preserved
+}
+```
+
+## When Immutability Patterns Make Sense
+
+```javascript
+// Immutability IS appropriate when:
+
+// 1. Replacing the entire state (e.g., from API response)
+const users = ref([])
+async function fetchUsers() {
+  users.value = await api.getUsers()  // Complete replacement is fine
+}
+
+// 2. When you need a snapshot for comparison
+const previousState = { ...currentState }  // For undo/redo
+
+// 3. When passing data to external libraries expecting immutable data
+const chartData = computed(() => [...rawData.value])  // Copy for chart lib
+```
+
+## The Vue Mental Model
+
+```javascript
+// Vue's reactivity is like a spreadsheet:
+// - Cell A1 contains a value (ref)
+// - Cell B1 has a formula referencing A1 (computed)
+// - Change A1, and B1 automatically updates
+
+const a1 = ref(10)
+const b1 = computed(() => a1.value * 2)
+
+// You CHANGE A1 (mutate), you don't create a new A1
+a1.value = 20  // b1 automatically becomes 40
+
+// This is fundamentally different from:
+// state = reducer(state, action)  // Functional/Redux pattern
+```
+
+## Reference
+- [Composition API FAQ](https://vuejs.org/guide/extras/composition-api-faq.html)
+- [Reactivity Fundamentals](https://vuejs.org/guide/essentials/reactivity-fundamentals.html)

package/skills/vue-debug-guides/reference/composition-api-script-setup-async-context.md

@@ -0,0 +1,203 @@
+---
+title: Top-Level await in script setup Preserves Component Context
+impact: HIGH
+impactDescription: Misunderstanding async context causes lifecycle hooks and watchers to silently fail
+type: gotcha
+tags: [vue3, composition-api, script-setup, async, await, suspense]
+---
+
+# Top-Level await in script setup Preserves Component Context
+
+**Impact: HIGH** - In `<script setup>`, top-level `await` statements preserve component context (allowing lifecycle hooks and watchers after `await`), but this is a special case. Nested async functions or callbacks lose context, causing lifecycle hooks to silently fail.
+
+Vue's compiler automatically injects context restoration after each top-level await in `<script setup>`. This doesn't apply to `setup()` function or nested async contexts.
+
+## Task Checklist
+
+- [ ] Understand that top-level await in `<script setup>` is specially handled
+- [ ] Never register lifecycle hooks in nested async functions
+- [ ] Use `<Suspense>` when using async `<script setup>` components
+- [ ] In regular `setup()`, never use await before lifecycle hook registration
+- [ ] Register hooks synchronously, then do async work inside them
+
+**Top-Level await Works (script setup only):**
+```vue
+<script setup>
+import { ref, onMounted, watch } from 'vue'
+
+// This is TOP-LEVEL await - Vue compiler preserves context
+const config = await fetchConfig()  // OK!
+
+// These hooks work because Vue restored context
+onMounted(() => {
+  console.log('This will run!')  // Works
+})
+
+watch(someRef, () => {
+  console.log('This will track!')  // Works
+})
+
+// Another top-level await - still OK
+const data = await fetchData(config.apiUrl)  // OK!
+
+// Still works after multiple awaits
+onMounted(() => {
+  console.log('This also runs!')  // Works
+})
+</script>
+
+<!-- IMPORTANT: Parent must use Suspense -->
+<template>
+  <Suspense>
+    <AsyncComponent />
+  </Suspense>
+</template>
+```
+
+**Nested Async Breaks Context:**
+```vue
+<script setup>
+import { ref, onMounted, watch } from 'vue'
+
+// WRONG: Nested async function - context lost after await
+async function initializeData() {
+  const config = await fetchConfig()
+
+  // BUG: This hook will NOT be registered!
+  // We're no longer in the synchronous setup context
+  onMounted(() => {
+    console.log('This will NEVER run!')  // Silent failure
+  })
+
+  // BUG: This watcher won't auto-dispose on unmount
+  watch(someRef, () => {
+    console.log('Memory leak - not cleaned up!')
+  })
+}
+
+// Calling the async function
+initializeData()  // Hooks inside won't work!
+
+// WRONG: Callbacks also lose context
+setTimeout(async () => {
+  await delay(100)
+  onMounted(() => {
+    console.log('Never runs!')  // Silent failure
+  })
+}, 0)
+</script>
+```
+
+**Correct Patterns:**
+```vue
+<script setup>
+import { ref, onMounted, watch } from 'vue'
+
+const data = ref(null)
+const config = ref(null)
+
+// CORRECT: Register hooks synchronously FIRST
+onMounted(async () => {
+  // Then do async work INSIDE the hook
+  config.value = await fetchConfig()
+  data.value = await fetchData(config.value.apiUrl)
+})
+
+// CORRECT: Watchers registered synchronously
+watch(config, async (newConfig) => {
+  if (newConfig) {
+    data.value = await fetchData(newConfig.apiUrl)
+  }
+})
+
+// Or use top-level await for initial data
+const initialConfig = await fetchConfig()  // OK - top level
+config.value = initialConfig
+
+onMounted(() => {
+  console.log('Works!')  // Context preserved by compiler
+})
+</script>
+```
+
+**setup() Function (Not script setup):**
+```javascript
+// In regular setup(), await ALWAYS breaks context
+export default {
+  async setup() {
+    const data = ref(null)
+
+    // WRONG: Hooks after await won't register
+    const config = await fetchConfig()
+
+    onMounted(() => {
+      console.log('Never runs!')  // Silent failure!
+    })
+
+    return { data }
+  }
+}
+
+// CORRECT: Register hooks before any await
+export default {
+  async setup() {
+    const data = ref(null)
+
+    // Register hooks FIRST (synchronous)
+    onMounted(async () => {
+      const config = await fetchConfig()
+      data.value = await fetchData(config)
+    })
+
+    // Now you can await if needed
+    // But hooks must be registered before this point
+
+    return { data }
+  }
+}
+```
+
+## Why This Happens
+
+```javascript
+// Vue tracks the "current component instance" during setup
+// This is like a global variable that gets set and cleared
+
+// During synchronous setup:
+function setup() {
+  currentInstance = this  // Vue sets this
+
+  onMounted(cb)  // Uses currentInstance to register
+
+  // After await, JavaScript resumes in a microtask
+  await something()
+
+  // currentInstance is now null or different!
+  onMounted(cb)  // Can't find the instance - silently fails
+}
+
+// <script setup> compiler adds restoration:
+// After each await, it injects: setCurrentInstance(savedInstance)
+```
+
+## Suspense Requirement
+
+```vue
+<!-- When using async script setup, parent needs Suspense -->
+<template>
+  <Suspense>
+    <!-- Async component with top-level await -->
+    <AsyncChild />
+
+    <!-- Optional: Loading state -->
+    <template #fallback>
+      <LoadingSpinner />
+    </template>
+  </Suspense>
+</template>
+```
+
+## Reference
+- [Composition API FAQ - Async Setup](https://vuejs.org/guide/extras/composition-api-faq.html)
+- [Composables - Async Without Await](https://antfu.me/posts/async-with-composition-api)
+- [Suspense](https://vuejs.org/guide/built-ins/suspense.html)

package/skills/vue-debug-guides/reference/composition-api-vs-react-hooks-differences.md

@@ -0,0 +1,156 @@
+---
+title: Vue Composition API Runs Once, Unlike React Hooks
+impact: MEDIUM
+impactDescription: Understanding this difference prevents over-engineering and React patterns that don't apply
+type: gotcha
+tags: [vue3, composition-api, react-hooks, setup, stale-closure]
+---
+
+# Vue Composition API Runs Once, Unlike React Hooks
+
+**Impact: MEDIUM** - Vue's `setup()` or `<script setup>` executes only once per component instance, while React Hooks run on every render. Developers coming from React often apply patterns (dependency arrays, excessive memoization, useCallback) that are unnecessary and counterproductive in Vue.
+
+Understanding this fundamental difference is crucial for writing idiomatic Vue code. Vue's approach eliminates entire categories of bugs (stale closures, exhaustive deps) that plague React applications.
+
+## Task Checklist
+
+- [ ] Don't implement "dependency arrays" - Vue tracks dependencies automatically
+- [ ] Don't wrap functions in "useCallback" equivalents - not needed in Vue
+- [ ] Don't use "useMemo" patterns - Vue's `computed()` handles this automatically
+- [ ] Understand that closures in Vue don't go "stale" like in React
+- [ ] Don't worry about "call order" - Vue composables can be conditional
+
+**React Patterns to Avoid in Vue:**
+```javascript
+// These patterns are UNNECESSARY in Vue - they solve React-specific problems
+
+// WRONG: Trying to implement dependency arrays (React pattern)
+watch(
+  [dep1, dep2, dep3],  // Vue tracks deps automatically in watchEffect
+  () => {
+    // ...
+  }
+)
+// Unless you specifically WANT to control which deps trigger the watcher,
+// prefer watchEffect() which auto-tracks
+
+// WRONG: Memoizing callbacks like useCallback
+const memoizedHandler = computed(() => {
+  return () => doSomething(state.value)
+})
+// In Vue, just define the function normally - no memoization needed
+
+// WRONG: Worrying about stale closures
+function useData() {
+  const data = ref(null)
+
+  // In React, this could capture stale 'data' - NOT in Vue!
+  // Vue refs are always current
+  const handler = () => {
+    console.log(data.value)  // Always gets current value
+  }
+
+  return { data, handler }
+}
+```
+
+**Correct Vue Patterns:**
+```javascript
+import { ref, computed, watchEffect } from 'vue'
+
+// CORRECT: Auto-dependency tracking with watchEffect
+const query = ref('')
+const filter = ref('all')
+
+watchEffect(() => {
+  // Vue automatically detects that this depends on query and filter
+  // No dependency array needed!
+  fetchResults(query.value, filter.value)
+})
+
+// CORRECT: computed() handles memoization automatically
+const expensiveResult = computed(() => {
+  // Only recalculates when dependencies actually change
+  return heavyComputation(data.value)
+})
+
+// CORRECT: Functions don't need memoization
+function handleClick() {
+  count.value++
+}
+// Just use it directly - no useCallback wrapper needed
+// <button @click="handleClick">
+
+// CORRECT: Closures always access current values
+const count = ref(0)
+const message = ref('')
+
+function logState() {
+  // This always logs CURRENT values, never stale ones
+  console.log(`Count: ${count.value}, Message: ${message.value}`)
+}
+
+setTimeout(() => {
+  logState()  // Gets current values even if called later
+}, 5000)
+```
+
+## Vue's Advantages Over React Hooks
+
+```javascript
+// 1. No stale closure problems
+const count = ref(0)
+
+onMounted(() => {
+  setInterval(() => {
+    // In React: would need useRef or deps array to avoid stale value
+    // In Vue: count.value is always current
+    console.log(count.value)
+  }, 1000)
+})
+
+// 2. Composables can be conditional
+if (featureEnabled) {
+  const { data } = useSomeFeature()  // This is FINE in Vue!
+}
+// In React: "Hooks cannot be conditional" - not a problem in Vue
+
+// 3. No exhaustive-deps linting headaches
+watchEffect(() => {
+  // Use any reactive values - Vue tracks them all automatically
+  // No ESLint rule yelling about missing dependencies
+  doSomething(a.value, b.value, c.value)
+})
+
+// 4. Child components don't need memoization by default
+// Vue's reactivity system only updates what actually changed
+// No need for React.memo() equivalents in most cases
+```
+
+## When Vue Patterns Differ
+
+```javascript
+// Setup runs once - so initialization happens once
+<script setup>
+import { ref, onMounted } from 'vue'
+
+// This code runs ONCE when component is created
+const data = ref(null)
+console.log('Setup running')  // Only logs once
+
+onMounted(() => {
+  console.log('Mounted')  // Only logs once
+})
+
+// If you need something to run on every reactive change,
+// use watch or watchEffect
+watchEffect(() => {
+  // This runs when dependencies change
+  console.log('Data changed:', data.value)
+})
+</script>
+```
+
+## Reference
+- [Composition API FAQ - Relationship with React Hooks](https://vuejs.org/guide/extras/composition-api-faq.html#relationship-with-react-hooks)
+- [Reactivity Fundamentals](https://vuejs.org/guide/essentials/reactivity-fundamentals.html)