@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/component-ref-requires-defineexpose.md

@@ -0,0 +1,176 @@
+---
+title: Component Refs Require defineExpose with Script Setup
+impact: HIGH
+impactDescription: Parent components cannot access child ref properties unless explicitly exposed
+type: gotcha
+tags: [vue3, template-refs, script-setup, defineExpose, component-communication]
+---
+
+# Component Refs Require defineExpose with Script Setup
+
+**Impact: HIGH** - Components using `<script setup>` are private by default. A parent component using a template ref to access a child will get an empty object unless the child explicitly exposes properties using `defineExpose()`. This is a fundamental change from Options API behavior.
+
+This catches many developers off-guard when migrating from Options API, where `this.$refs.child` gave full access to the child instance.
+
+## Task Checklist
+
+- [ ] Use `defineExpose()` to explicitly expose properties/methods to parent refs
+- [ ] Only expose what's necessary - keep component internals private
+- [ ] Document exposed APIs as they form your component's public interface
+- [ ] Prefer props/emit for parent-child communication; use refs sparingly
+- [ ] Call defineExpose before any await operation (see async caveat)
+
+**Incorrect:**
+```vue
+<!-- ChildComponent.vue -->
+<script setup>
+import { ref } from 'vue'
+
+const count = ref(0)
+const internalState = ref('private')
+
+function increment() {
+  count.value++
+}
+
+function reset() {
+  count.value = 0
+}
+
+// WRONG: Nothing exposed - parent ref sees empty object
+</script>
+
+<template>
+  <div>{{ count }}</div>
+</template>
+```
+
+```vue
+<!-- ParentComponent.vue -->
+<script setup>
+import { ref, onMounted } from 'vue'
+import ChildComponent from './ChildComponent.vue'
+
+const childRef = ref(null)
+
+onMounted(() => {
+  // WRONG: childRef.value is {} - empty object!
+  console.log(childRef.value.count) // undefined
+  childRef.value.increment() // TypeError: not a function
+})
+</script>
+
+<template>
+  <ChildComponent ref="childRef" />
+</template>
+```
+
+**Correct:**
+```vue
+<!-- ChildComponent.vue -->
+<script setup>
+import { ref } from 'vue'
+
+const count = ref(0)
+const internalState = ref('private') // Keep this private
+
+function increment() {
+  count.value++
+}
+
+function reset() {
+  count.value = 0
+}
+
+// CORRECT: Explicitly expose public API
+defineExpose({
+  count,      // Expose the ref
+  increment,  // Expose methods
+  reset
+  // internalState NOT exposed - stays private
+})
+</script>
+
+<template>
+  <div>{{ count }}</div>
+</template>
+```
+
+```vue
+<!-- ParentComponent.vue -->
+<script setup>
+import { ref, onMounted } from 'vue'
+import ChildComponent from './ChildComponent.vue'
+
+const childRef = ref(null)
+
+onMounted(() => {
+  // CORRECT: Can access exposed properties
+  console.log(childRef.value.count) // 0
+  childRef.value.increment() // Works!
+
+  // internalState is not accessible (private)
+  console.log(childRef.value.internalState) // undefined
+})
+</script>
+
+<template>
+  <ChildComponent ref="childRef" />
+</template>
+```
+
+```vue
+<!-- Input wrapper example - exposing native element -->
+<script setup>
+import { ref } from 'vue'
+
+const inputEl = ref(null)
+
+// Expose the native input for parent to access (e.g., for focus)
+defineExpose({
+  focus: () => inputEl.value?.focus(),
+  blur: () => inputEl.value?.blur(),
+  // Or expose the element directly
+  el: inputEl
+})
+</script>
+
+<template>
+  <input ref="inputEl" v-bind="$attrs" />
+</template>
+```
+
+```javascript
+// Options API equivalent using expose option
+export default {
+  expose: ['count', 'increment', 'reset'],
+  data() {
+    return {
+      count: 0,
+      internalState: 'private'
+    }
+  },
+  methods: {
+    increment() { this.count++ },
+    reset() { this.count = 0 }
+  }
+}
+```
+
+## Best Practice Reminder
+
+Component refs create tight coupling between parent and child. Prefer standard patterns:
+
+```vue
+<!-- PREFERRED: Use props and emit for communication -->
+<script setup>
+const props = defineProps(['modelValue'])
+const emit = defineEmits(['update:modelValue'])
+</script>
+
+<!-- Only use refs for imperative actions like focus(), scrollTo(), etc. -->
+```
+
+## Reference
+- [Vue.js Component Refs](https://vuejs.org/guide/essentials/template-refs.html#ref-on-component)
+- [Script Setup - defineExpose](https://vuejs.org/api/sfc-script-setup.html#defineexpose)

package/skills/vue-debug-guides/reference/composable-avoid-hidden-side-effects.md

@@ -0,0 +1,208 @@
+---
+title: Avoid Hidden Side Effects in Composables
+impact: HIGH
+impactDescription: Side effects hidden in composables make debugging difficult and create implicit coupling between components
+type: best-practice
+tags: [vue3, composables, composition-api, side-effects, provide-inject, global-state]
+---
+
+# Avoid Hidden Side Effects in Composables
+
+**Impact: HIGH** - Composables should encapsulate stateful logic, not hide side effects that affect things outside their scope. Hidden side effects like modifying global state, using provide/inject internally, or manipulating the DOM directly make composables unpredictable and hard to debug.
+
+When a composable has unexpected side effects, consumers can't reason about what calling it will do. This leads to bugs that are difficult to trace and composables that can't be safely reused.
+
+## Task Checklist
+
+- [ ] Avoid using provide/inject inside composables (make dependencies explicit)
+- [ ] Don't modify Pinia/Vuex store state internally (accept store as parameter instead)
+- [ ] Don't manipulate DOM directly (use template refs passed as arguments)
+- [ ] Document any unavoidable side effects clearly
+- [ ] Keep composables focused on returning reactive state and methods
+
+**Incorrect:**
+```javascript
+// WRONG: Hidden provide/inject dependency
+export function useTheme() {
+  // Consumer has no idea this depends on a provided theme
+  const theme = inject('theme')  // What if nothing provides this?
+
+  const isDark = computed(() => theme?.mode === 'dark')
+  return { isDark }
+}
+
+// WRONG: Modifying global store internally
+import { useUserStore } from '@/stores/user'
+
+export function useLogin() {
+  const userStore = useUserStore()
+
+  async function login(credentials) {
+    const user = await api.login(credentials)
+    // Hidden side effect: modifying global state
+    userStore.setUser(user)
+    userStore.setToken(user.token)
+    // Consumer doesn't know the store was modified!
+  }
+
+  return { login }
+}
+
+// WRONG: Hidden DOM manipulation
+export function useFocusTrap() {
+  onMounted(() => {
+    // Which element? Consumer has no control
+    document.querySelector('.modal')?.focus()
+  })
+}
+
+// WRONG: Hidden provide that affects descendants
+export function useFormContext() {
+  const form = reactive({ values: {}, errors: {} })
+  // Components calling this have no idea it provides something
+  provide('form-context', form)
+  return form
+}
+```
+
+**Correct:**
+```javascript
+// CORRECT: Explicit dependency injection
+export function useTheme(injectedTheme) {
+  // If no theme passed, consumer must handle it
+  const theme = injectedTheme ?? { mode: 'light' }
+
+  const isDark = computed(() => theme.mode === 'dark')
+  return { isDark }
+}
+
+// Usage - dependency is explicit
+const theme = inject('theme', { mode: 'light' })
+const { isDark } = useTheme(theme)
+
+// CORRECT: Return actions, let consumer decide when to call them
+export function useLogin() {
+  const user = ref(null)
+  const token = ref(null)
+  const isLoading = ref(false)
+  const error = ref(null)
+
+  async function login(credentials) {
+    isLoading.value = true
+    error.value = null
+    try {
+      const response = await api.login(credentials)
+      user.value = response.user
+      token.value = response.token
+      return response
+    } catch (e) {
+      error.value = e
+      throw e
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  return { user, token, isLoading, error, login }
+}
+
+// Consumer decides what to do with the result
+const { user, token, login } = useLogin()
+const userStore = useUserStore()
+
+async function handleLogin(credentials) {
+  await login(credentials)
+  // Consumer explicitly updates the store
+  userStore.setUser(user.value)
+  userStore.setToken(token.value)
+}
+
+// CORRECT: Accept element as parameter
+export function useFocusTrap(targetRef) {
+  onMounted(() => {
+    targetRef.value?.focus()
+  })
+
+  onUnmounted(() => {
+    // Cleanup focus trap
+  })
+}
+
+// Usage - consumer controls which element
+const modalRef = ref(null)
+useFocusTrap(modalRef)
+
+// CORRECT: Separate composable from provider
+export function useFormContext() {
+  const form = reactive({ values: {}, errors: {} })
+  return form
+}
+
+// In parent component - explicit provide
+const form = useFormContext()
+provide('form-context', form)
+```
+
+## Acceptable Side Effects (With Documentation)
+
+Some side effects are acceptable when they're the core purpose of the composable:
+
+```javascript
+/**
+ * Tracks mouse position globally.
+ *
+ * SIDE EFFECTS:
+ * - Adds 'mousemove' event listener to window (cleaned up on unmount)
+ *
+ * @returns {Object} Mouse coordinates { x, y }
+ */
+export function useMouse() {
+  const x = ref(0)
+  const y = ref(0)
+
+  // This side effect is the whole point of the composable
+  // and is properly cleaned up
+  onMounted(() => window.addEventListener('mousemove', update))
+  onUnmounted(() => window.removeEventListener('mousemove', update))
+
+  function update(event) {
+    x.value = event.pageX
+    y.value = event.pageY
+  }
+
+  return { x, y }
+}
+```
+
+## Pattern: Dependency Injection for Flexibility
+
+```javascript
+// Composable accepts its dependencies
+export function useDataFetcher(apiClient, cache = null) {
+  const data = ref(null)
+
+  async function fetch(url) {
+    if (cache) {
+      const cached = cache.get(url)
+      if (cached) {
+        data.value = cached
+        return
+      }
+    }
+
+    data.value = await apiClient.get(url)
+    cache?.set(url, data.value)
+  }
+
+  return { data, fetch }
+}
+
+// Usage - dependencies are explicit and testable
+const apiClient = inject('apiClient')
+const cache = inject('cache', null)
+const { data, fetch } = useDataFetcher(apiClient, cache)
+```
+
+## Reference
+- [Vue.js Composables](https://vuejs.org/guide/reusability/composables.html)
+- [Common Mistakes Creating Composition Functions](https://www.telerik.com/blogs/common-mistakes-creating-composition-functions-vue)

package/skills/vue-debug-guides/reference/composable-call-location-restrictions.md

@@ -0,0 +1,141 @@
+---
+title: Call Composables Only in Setup Context Synchronously
+impact: HIGH
+impactDescription: Composables called outside setup context or asynchronously fail to register lifecycle hooks and may cause memory leaks
+type: gotcha
+tags: [vue3, composables, composition-api, setup, async, lifecycle]
+---
+
+# Call Composables Only in Setup Context Synchronously
+
+**Impact: HIGH** - Composables must be called synchronously within `<script setup>`, the `setup()` function, or lifecycle hooks. Calling composables asynchronously (after await), in callbacks, or outside component context prevents Vue from associating lifecycle hooks with the component instance, causing silent failures.
+
+This is critical because composables often register `onMounted` and `onUnmounted` hooks internally. If called in the wrong context, these hooks are never registered, leading to uninitialized state or memory leaks.
+
+## Task Checklist
+
+- [ ] Call all composables at the top level of `<script setup>` or `setup()`
+- [ ] Never call composables inside async callbacks, setTimeout, or Promise.then
+- [ ] Never call composables conditionally (if/else) - call unconditionally and handle the condition inside
+- [ ] Never call composables inside loops - restructure to call once with array data
+- [ ] Exception: Composables CAN be called in lifecycle hooks like `onMounted`
+
+**Incorrect:**
+```vue
+<script setup>
+import { useFetch } from './composables/useFetch'
+import { useAuth } from './composables/useAuth'
+
+// WRONG: Composable called after await
+const config = await loadConfig()
+const { data } = useFetch(config.apiUrl)  // Lifecycle hooks won't register!
+
+// WRONG: Composable called conditionally
+if (someCondition) {
+  const { user } = useAuth()  // Inconsistent hook registration!
+}
+
+// WRONG: Composable called in callback
+setTimeout(() => {
+  const { data } = useFetch('/api/delayed')  // No component context!
+}, 1000)
+
+// WRONG: Composable called in loop
+for (const url of urls) {
+  const { data } = useFetch(url)  // Creates multiple instances incorrectly
+}
+</script>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+import { useFetch } from './composables/useFetch'
+import { useAuth } from './composables/useAuth'
+
+// CORRECT: Call composables synchronously at top level
+const { user, isAuthenticated } = useAuth()
+const apiUrl = ref('/api/default')
+const { data, execute } = useFetch(apiUrl)
+
+// Handle async config loading differently
+onMounted(async () => {
+  const config = await loadConfig()
+  apiUrl.value = config.apiUrl  // Update the ref, composable reacts
+})
+
+// CORRECT: Handle condition inside, not outside
+const showUserData = computed(() => isAuthenticated.value && someCondition)
+
+// CORRECT: For multiple URLs, use a different pattern
+const urls = ref(['/api/a', '/api/b', '/api/c'])
+const results = ref([])
+
+// Either fetch in onMounted or use a composable designed for arrays
+onMounted(async () => {
+  results.value = await Promise.all(urls.value.map(url => fetch(url)))
+})
+</script>
+```
+
+## Exception: Calling in Lifecycle Hooks
+
+Composables CAN be called inside lifecycle hooks because Vue maintains the component context:
+
+```vue
+<script setup>
+import { onMounted } from 'vue'
+import { useEventListener } from '@vueuse/core'
+
+// CORRECT: Called in lifecycle hook - component context is available
+onMounted(() => {
+  // This works because we're still in the component's execution context
+  useEventListener(document, 'visibilitychange', handleVisibility)
+})
+</script>
+```
+
+## Special Case: Async Setup in `<script setup>`
+
+Top-level await in `<script setup>` is special - Vue's compiler automatically preserves context:
+
+```vue
+<script setup>
+import { useFetch } from './composables/useFetch'
+
+// CORRECT: Top-level await in <script setup> preserves context
+// Vue compiler handles this specially
+const config = await loadConfig()
+const { data } = useFetch(config.apiUrl)  // This works!
+
+// But nested awaits still break context:
+async function initLater() {
+  await delay(1000)
+  const { data } = useFetch('/api/late')  // WRONG: This won't work!
+}
+</script>
+```
+
+## Why This Matters
+
+When you call a composable, Vue needs to know which component instance to associate it with. This association happens through an internal "current instance" that's only set during synchronous setup execution.
+
+```javascript
+// Inside a composable
+export function useFetch(url) {
+  const data = ref(null)
+
+  // These need the current component instance!
+  onMounted(() => { /* ... */ })
+  onUnmounted(() => { /* cleanup */ })
+
+  // If called outside setup context, Vue can't find the instance
+  // and these hooks are silently ignored
+  return { data }
+}
+```
+
+## Reference
+- [Vue.js Composables - Usage Restrictions](https://vuejs.org/guide/reusability/composables.html#usage-restrictions)
+- [Vue.js Composition API - Setup Context](https://vuejs.org/api/composition-api-setup.html)

package/skills/vue-debug-guides/reference/composable-naming-return-pattern.md

@@ -0,0 +1,139 @@
+---
+title: Follow Composable Naming Convention and Return Pattern
+impact: MEDIUM
+impactDescription: Inconsistent composable patterns lead to confusing APIs and reactivity issues when destructuring
+type: best-practice
+tags: [vue3, composables, composition-api, naming, conventions, refs]
+---
+
+# Follow Composable Naming Convention and Return Pattern
+
+**Impact: MEDIUM** - Vue composables should follow established conventions: prefix names with "use" and return plain objects containing refs (not reactive objects). Returning reactive objects causes reactivity loss when destructuring, while inconsistent naming makes code harder to understand.
+
+## Task Checklist
+
+- [ ] Name composables with "use" prefix (e.g., `useMouse`, `useFetch`, `useAuth`)
+- [ ] Return a plain object containing refs, not a reactive object
+- [ ] Allow both destructuring and object-style access
+- [ ] Document the returned refs for consumers
+
+**Incorrect:**
+```javascript
+// WRONG: No "use" prefix - unclear it's a composable
+export function mousePosition() {
+  const x = ref(0)
+  const y = ref(0)
+  return { x, y }
+}
+
+// WRONG: Returning reactive object - destructuring loses reactivity
+export function useMouse() {
+  const state = reactive({
+    x: 0,
+    y: 0
+  })
+  // When consumer destructures: const { x, y } = useMouse()
+  // x and y become plain values, not reactive!
+  return state
+}
+
+// WRONG: Returning single ref directly - inconsistent API
+export function useCounter() {
+  const count = ref(0)
+  return count  // Consumer must use .value everywhere
+}
+```
+
+**Correct:**
+```javascript
+// CORRECT: "use" prefix and returns plain object with refs
+export function useMouse() {
+  const x = ref(0)
+  const y = ref(0)
+
+  function update(event) {
+    x.value = event.pageX
+    y.value = event.pageY
+  }
+
+  onMounted(() => window.addEventListener('mousemove', update))
+  onUnmounted(() => window.removeEventListener('mousemove', update))
+
+  // Return plain object containing refs
+  return { x, y }
+}
+
+// Consumer can destructure and keep reactivity
+const { x, y } = useMouse()
+watch(x, (newX) => console.log('x changed:', newX))  // Works!
+
+// Or use as object if preferred
+const mouse = useMouse()
+console.log(mouse.x.value)
+```
+
+## Using reactive() Wrapper for Auto-Unwrapping
+
+If consumers prefer auto-unwrapping (no `.value`), they can wrap the result:
+
+```javascript
+import { reactive } from 'vue'
+import { useMouse } from './composables/useMouse'
+
+// Wrapping in reactive() links the refs
+const mouse = reactive(useMouse())
+
+// Now access without .value
+console.log(mouse.x)  // Auto-unwrapped, still reactive
+
+// But DON'T destructure from this!
+const { x } = reactive(useMouse())  // WRONG: loses reactivity again
+```
+
+## Pattern: Returning Both State and Actions
+
+```javascript
+// Composable with state AND methods
+export function useCounter(initialValue = 0) {
+  const count = ref(initialValue)
+  const doubleCount = computed(() => count.value * 2)
+
+  function increment() {
+    count.value++
+  }
+
+  function decrement() {
+    count.value--
+  }
+
+  function reset() {
+    count.value = initialValue
+  }
+
+  // Return all refs and functions in plain object
+  return {
+    count,
+    doubleCount,
+    increment,
+    decrement,
+    reset
+  }
+}
+
+// Usage
+const { count, doubleCount, increment, reset } = useCounter(10)
+```
+
+## Naming Convention Examples
+
+| Good Name | Bad Name | Reason |
+|-----------|----------|--------|
+| `useFetch` | `fetch` | Conflicts with native fetch |
+| `useAuth` | `authStore` | "Store" implies Pinia/Vuex |
+| `useLocalStorage` | `localStorage` | Conflicts with native API |
+| `useFormValidation` | `validateForm` | Sounds like a one-shot function |
+| `useWindowSize` | `getWindowSize` | "get" implies synchronous getter |
+
+## Reference
+- [Vue.js Composables - Conventions and Best Practices](https://vuejs.org/guide/reusability/composables.html#conventions-and-best-practices)
+- [Vue.js Composables - Return Values](https://vuejs.org/guide/reusability/composables.html#return-values)