@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/provide-inject-debugging-challenges.md

@@ -0,0 +1,203 @@
+---
+title: Provide/Inject Has Limited DevTools Support - Plan for Debugging
+impact: LOW
+impactDescription: Unlike props and state, provided values are harder to trace in Vue DevTools, making debugging more challenging
+type: gotcha
+tags: [vue3, provide-inject, debugging, devtools, architecture]
+---
+
+# Provide/Inject Has Limited DevTools Support - Plan for Debugging
+
+**Impact: LOW** - While provide/inject is powerful for avoiding prop drilling, it creates less visible data flow than props. Provided values are not as easily inspectable in Vue DevTools, and tracing where a value comes from requires navigating the component tree manually.
+
+## Task Checklist
+
+- [ ] Document provided values at the provider component level
+- [ ] Use descriptive Symbol descriptions for easier identification
+- [ ] Consider adding development-only logging for provided state changes
+- [ ] Keep provide/inject chains shallow when possible
+- [ ] Prefer Pinia for complex state that needs DevTools integration
+
+## The Challenge
+
+Unlike props which are clearly visible in Vue DevTools for each component, provided values:
+
+1. Don't show which ancestor provided them
+2. Require manual navigation to find the provider
+3. Don't show in the standard props/data panels
+4. Can be shadowed by closer ancestors using the same key
+
+## Strategies for Better Debugging
+
+### 1. Use Descriptive Symbol Names
+
+```js
+// injection-keys.js
+
+// BETTER: Descriptive names appear in errors and debugging
+export const UserAuthKey = Symbol('UserAuthenticationState')
+export const ThemeConfigKey = Symbol('ThemeConfiguration')
+export const FormContextKey = Symbol('FormValidationContext')
+
+// WORSE: Generic names are harder to trace
+export const UserKey = Symbol()
+export const ThemeKey = Symbol('theme')
+```
+
+### 2. Document Providers Clearly
+
+```vue
+<!-- AuthProvider.vue -->
+<script setup>
+/**
+ * Authentication Provider
+ *
+ * Provides:
+ * - UserAuthKey: Current user state (Ref<User | null>)
+ * - AuthActionsKey: { login, logout, refresh }
+ *
+ * Must wrap any component that needs authentication state.
+ */
+import { provide, ref, readonly } from 'vue'
+import { UserAuthKey, AuthActionsKey } from '@/injection-keys'
+
+const user = ref(null)
+
+// ... implementation
+
+provide(UserAuthKey, readonly(user))
+provide(AuthActionsKey, { login, logout, refresh })
+</script>
+```
+
+### 3. Development-Only Logging
+
+```js
+// composables/useProvideWithLogging.js
+import { provide, watch, getCurrentInstance } from 'vue'
+
+export function useProvideWithLogging(key, value, name) {
+  provide(key, value)
+
+  if (import.meta.env.DEV) {
+    const instance = getCurrentInstance()
+    const componentName = instance?.type?.name || 'Unknown'
+
+    console.log(`[Provide] ${name} provided by <${componentName}>`)
+
+    // Log reactive changes
+    if (value && typeof value === 'object' && 'value' in value) {
+      watch(value, (newVal) => {
+        console.log(`[Provide] ${name} changed:`, newVal)
+      }, { deep: true })
+    }
+  }
+}
+```
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useProvideWithLogging } from '@/composables/useProvideWithLogging'
+import { ThemeKey } from '@/injection-keys'
+
+const theme = ref('dark')
+
+// In development, logs when provided and when changed
+useProvideWithLogging(ThemeKey, theme, 'Theme')
+</script>
+```
+
+### 4. Inject with Missing Provider Warnings
+
+```js
+// composables/useSafeInject.js
+import { inject, getCurrentInstance } from 'vue'
+
+export function useSafeInject(key, fallback, keyName) {
+  const value = inject(key, undefined)
+
+  if (value === undefined) {
+    const instance = getCurrentInstance()
+    const componentName = instance?.type?.name || 'Unknown'
+
+    if (import.meta.env.DEV) {
+      console.warn(
+        `[Inject] ${keyName || String(key)} not provided. ` +
+        `Component <${componentName}> is using fallback value. ` +
+        `Ensure a provider exists in the ancestor chain.`
+      )
+    }
+
+    return typeof fallback === 'function' ? fallback() : fallback
+  }
+
+  return value
+}
+```
+
+```vue
+<script setup>
+import { useSafeInject } from '@/composables/useSafeInject'
+import { ThemeKey } from '@/injection-keys'
+
+// Warns in dev if no provider found
+const theme = useSafeInject(ThemeKey, () => ({ mode: 'light' }), 'ThemeConfig')
+</script>
+```
+
+### 5. Create Provider Registry for Complex Apps
+
+```js
+// utils/provider-registry.js
+const providerRegistry = new Map()
+
+export function registerProvider(key, componentName, value) {
+  if (import.meta.env.DEV) {
+    providerRegistry.set(key, {
+      componentName,
+      value,
+      timestamp: Date.now()
+    })
+  }
+}
+
+export function getProviderInfo(key) {
+  return providerRegistry.get(key)
+}
+
+// For DevTools custom plugin or debugging
+export function getAllProviders() {
+  return Object.fromEntries(providerRegistry)
+}
+
+// Expose to window for console debugging
+if (import.meta.env.DEV) {
+  window.__VUE_PROVIDERS__ = {
+    getAll: getAllProviders,
+    get: getProviderInfo
+  }
+}
+```
+
+## When to Use Pinia Instead
+
+If you find yourself needing extensive debugging for state:
+
+| Use Provide/Inject | Use Pinia |
+|-------------------|-----------|
+| Component library internals | Application-wide state |
+| Theme/locale configuration | User session data |
+| Form context | Shopping cart |
+| Simple parent-child sharing | Complex state with actions |
+| Plugin configuration | State that needs time-travel debugging |
+
+Pinia provides excellent DevTools integration with:
+- State inspection
+- Time-travel debugging
+- Action logging
+- Hot module replacement
+
+## Reference
+- [Vue DevTools](https://devtools.vuejs.org/)
+- [Pinia DevTools](https://pinia.vuejs.org/core-concepts/index.html#devtools)

package/skills/vue-debug-guides/reference/provide-inject-default-value-factory.md

@@ -0,0 +1,244 @@
+---
+title: Use Factory Functions for Non-Primitive Inject Default Values
+impact: MEDIUM
+impactDescription: Using object literals as default values creates shared references across all consuming components
+type: gotcha
+tags: [vue3, provide-inject, composition-api, memory, shared-state]
+---
+
+# Use Factory Functions for Non-Primitive Inject Default Values
+
+**Impact: MEDIUM** - When providing default values for `inject()`, using an object literal creates a single shared reference. All components using that default will share the same object, leading to unexpected state sharing and bugs.
+
+## Task Checklist
+
+- [ ] Always use factory functions for object/array default values in inject
+- [ ] Pass `true` as the third argument to enable factory mode in Composition API
+- [ ] Use the object syntax with factory function in Options API
+- [ ] Only use literal defaults for primitive values (strings, numbers, booleans)
+
+## The Gotcha: Shared Default References
+
+**Wrong - Object literal creates shared reference:**
+```vue
+<script setup>
+import { inject } from 'vue'
+
+// WRONG: All components without a provider share this SAME object
+const config = inject('config', { debug: false, apiUrl: '' })
+
+// If one component does this:
+config.debug = true
+
+// ALL other components using this default now have debug: true!
+</script>
+```
+
+**Correct - Factory function creates unique instance:**
+```vue
+<script setup>
+import { inject } from 'vue'
+
+// CORRECT: Each component gets its own object
+// Third argument `true` indicates the second arg is a factory function
+const config = inject('config', () => ({ debug: false, apiUrl: '' }), true)
+</script>
+```
+
+## API Explanation
+
+The `inject()` function has multiple signatures:
+
+```ts
+// Simple default value (OK for primitives)
+inject(key, defaultValue)
+
+// Factory function for non-primitives (REQUIRED for objects/arrays)
+inject(key, factoryFunction, true)
+```
+
+The third argument `true` tells Vue that the second argument is a factory function, not the default value itself.
+
+## Examples
+
+### Primitive Defaults (No Factory Needed)
+
+```vue
+<script setup>
+import { inject } from 'vue'
+
+// Primitives are safe without factory
+const count = inject('count', 0)
+const name = inject('name', 'Guest')
+const enabled = inject('enabled', false)
+</script>
+```
+
+### Object Defaults (Factory Required)
+
+```vue
+<script setup>
+import { inject } from 'vue'
+
+// Objects MUST use factory
+const user = inject('user', () => ({
+  id: null,
+  name: 'Anonymous',
+  preferences: {}
+}), true)
+
+const settings = inject('settings', () => ({
+  theme: 'light',
+  language: 'en',
+  notifications: true
+}), true)
+</script>
+```
+
+### Array Defaults (Factory Required)
+
+```vue
+<script setup>
+import { inject } from 'vue'
+
+// Arrays MUST use factory
+const items = inject('items', () => [], true)
+const permissions = inject('permissions', () => ['read'], true)
+</script>
+```
+
+### Class Instance Defaults (Factory Required)
+
+```vue
+<script setup>
+import { inject } from 'vue'
+import { Logger } from '@/utils/logger'
+
+// Class instances MUST use factory
+const logger = inject('logger', () => new Logger({ level: 'warn' }), true)
+</script>
+```
+
+## Options API Syntax
+
+In Options API, use the object syntax with a `default` factory function:
+
+```js
+export default {
+  inject: {
+    // Primitive - can use literal
+    theme: {
+      from: 'theme',
+      default: 'light'
+    },
+
+    // Object - MUST use factory
+    config: {
+      from: 'config',
+      default: () => ({ debug: false })
+    },
+
+    // Array - MUST use factory
+    permissions: {
+      from: 'permissions',
+      default: () => []
+    }
+  }
+}
+```
+
+## Real-World Example: Form Context
+
+```vue
+<!-- FormProvider.vue -->
+<script setup>
+import { provide, reactive } from 'vue'
+
+const formContext = reactive({
+  values: {},
+  errors: {},
+  touched: {},
+  isSubmitting: false
+})
+
+provide('formContext', formContext)
+</script>
+
+<!-- FormField.vue (might be used outside FormProvider) -->
+<script setup>
+import { inject } from 'vue'
+
+// Safe default that won't be shared
+const formContext = inject('formContext', () => ({
+  values: {},
+  errors: {},
+  touched: {},
+  isSubmitting: false,
+  // Mark as standalone mode
+  isStandalone: true
+}), true)
+
+// Component works both inside and outside FormProvider
+</script>
+```
+
+## TypeScript: Typing Factory Defaults
+
+```ts
+import { inject } from 'vue'
+import type { InjectionKey } from 'vue'
+
+interface Config {
+  apiUrl: string
+  debug: boolean
+  features: string[]
+}
+
+const ConfigKey: InjectionKey<Config> = Symbol('config')
+
+// TypeScript understands the factory return type
+const config = inject(ConfigKey, () => ({
+  apiUrl: 'https://api.example.com',
+  debug: false,
+  features: []
+}), true)
+```
+
+## Common Mistake in Testing
+
+This gotcha often appears in tests where components are rendered without providers:
+
+```ts
+// test.spec.ts
+import { mount } from '@vue/test-utils'
+import MyComponent from './MyComponent.vue'
+
+// Without provider, all test instances share the wrong default
+it('test 1', () => {
+  const wrapper = mount(MyComponent)
+  wrapper.vm.config.debug = true // Pollutes other tests!
+})
+
+it('test 2', () => {
+  const wrapper = mount(MyComponent)
+  // Might fail because debug is still true from test 1
+})
+```
+
+**Fix: Use factory functions in the component, or provide in tests:**
+
+```ts
+it('test with provider', () => {
+  const wrapper = mount(MyComponent, {
+    global: {
+      provide: {
+        config: { debug: false, apiUrl: '' }
+      }
+    }
+  })
+})
+```
+
+## Reference
+- [Vue.js inject() API Reference](https://vuejs.org/api/composition-api-dependency-injection.html#inject)
+- [Vue.js Provide/Inject Guide](https://vuejs.org/guide/components/provide-inject.html)

package/skills/vue-debug-guides/reference/provide-inject-reactivity-not-automatic.md

@@ -0,0 +1,226 @@
+---
+title: Provide/Inject Values Are Not Reactive by Default
+impact: HIGH
+impactDescription: Provided primitive values lose reactivity, causing injecting components to not update when the source value changes
+type: gotcha
+tags: [vue3, provide-inject, reactivity, composition-api, options-api]
+---
+
+# Provide/Inject Values Are Not Reactive by Default
+
+**Impact: HIGH** - A common misconception is that provide/inject automatically maintains reactivity. By default, provided primitive values are NOT reactive. If the provided value changes in the provider, injecting components will NOT be updated.
+
+## Task Checklist
+
+- [ ] Always wrap primitive values in `ref()` before providing
+- [ ] Use `computed()` in Options API `provide()` for reactive data
+- [ ] Never destructure refs when providing - pass the ref directly
+- [ ] Understand that provided refs are NOT auto-unwrapped in injectors
+
+## The Gotcha: Primitives Lose Reactivity
+
+**Wrong - Primitive loses reactivity:**
+```vue
+<!-- Provider.vue -->
+<script setup>
+import { ref, provide } from 'vue'
+
+const count = ref(0)
+
+// WRONG: Providing the unwrapped value loses reactivity
+provide('count', count.value) // Provides 0, not a reactive value
+
+function increment() {
+  count.value++ // Injector will NOT see this change
+}
+</script>
+```
+
+```vue
+<!-- Injector.vue -->
+<script setup>
+import { inject } from 'vue'
+
+const count = inject('count') // Gets 0, forever static
+</script>
+
+<template>
+  <!-- This will always show 0 -->
+  <div>Count: {{ count }}</div>
+</template>
+```
+
+**Correct - Provide the ref itself:**
+```vue
+<!-- Provider.vue -->
+<script setup>
+import { ref, provide } from 'vue'
+
+const count = ref(0)
+
+// CORRECT: Provide the ref, not the value
+provide('count', count)
+
+function increment() {
+  count.value++ // Injector WILL see this change
+}
+</script>
+```
+
+```vue
+<!-- Injector.vue -->
+<script setup>
+import { inject } from 'vue'
+
+// The ref is injected as-is, maintaining reactivity
+const count = inject('count')
+</script>
+
+<template>
+  <!-- Access .value in script, auto-unwrapped in template -->
+  <div>Count: {{ count }}</div>
+</template>
+```
+
+## Options API: Use computed() for Reactivity
+
+In Options API, the `provide` option with plain properties is NOT reactive:
+
+**Wrong - Options API without computed:**
+```js
+export default {
+  data() {
+    return {
+      message: 'Hello'
+    }
+  },
+  // WRONG: This is NOT reactive
+  provide() {
+    return {
+      message: this.message // Provides 'Hello' as a static string
+    }
+  }
+}
+```
+
+**Correct - Use computed() in Options API:**
+```js
+import { computed } from 'vue'
+
+export default {
+  data() {
+    return {
+      message: 'Hello'
+    }
+  },
+  provide() {
+    return {
+      // CORRECT: Wrap in computed for reactivity
+      message: computed(() => this.message)
+    }
+  }
+}
+```
+
+## Understanding Ref Behavior in Inject
+
+When you provide a ref, it is injected as-is and NOT auto-unwrapped:
+
+```vue
+<!-- Provider.vue -->
+<script setup>
+import { ref, provide } from 'vue'
+
+const user = ref({ name: 'John' })
+provide('user', user)
+</script>
+```
+
+```vue
+<!-- Injector.vue -->
+<script setup>
+import { inject } from 'vue'
+
+const user = inject('user')
+
+// In script, access with .value
+console.log(user.value.name) // 'John'
+
+function updateName(newName) {
+  user.value.name = newName // Works, but mutations should be in provider
+}
+</script>
+
+<template>
+  <!-- In template, auto-unwrapped at top level -->
+  <div>{{ user.name }}</div>
+</template>
+```
+
+## Providing Reactive Objects
+
+Reactive objects (created with `reactive()`) maintain reactivity when provided:
+
+```vue
+<!-- Provider.vue -->
+<script setup>
+import { reactive, provide } from 'vue'
+
+const state = reactive({
+  count: 0,
+  message: 'Hello'
+})
+
+provide('state', state)
+</script>
+```
+
+```vue
+<!-- Injector.vue -->
+<script setup>
+import { inject } from 'vue'
+
+const state = inject('state')
+// state.count and state.message are reactive
+</script>
+```
+
+## Common Mistake: Destructuring Breaks Reactivity
+
+**Wrong - Destructuring provided reactive state:**
+```vue
+<script setup>
+import { inject } from 'vue'
+
+// WRONG: Destructuring loses reactivity
+const { count, message } = inject('state')
+// count and message are now static values
+</script>
+```
+
+**Correct - Keep the reference intact:**
+```vue
+<script setup>
+import { inject, toRefs } from 'vue'
+
+const state = inject('state')
+// Use state.count and state.message directly
+
+// Or use toRefs if you need destructured reactive refs
+const { count, message } = toRefs(state)
+</script>
+```
+
+## Debugging Tip
+
+If your injected value isn't updating:
+
+1. Check if you provided `ref.value` instead of `ref`
+2. Check if you destructured a reactive object
+3. In Options API, ensure you used `computed()`
+4. Use Vue DevTools to inspect the provided values
+
+## Reference
+- [Vue.js Provide/Inject - Working with Reactivity](https://vuejs.org/guide/components/provide-inject.html#working-with-reactivity)
+- [How to make provide/inject reactive - LogRocket Blog](https://blog.logrocket.com/how-to-make-provide-inject-reactive/)
+- [GitHub Issue: Inject/Provide is not reactive](https://github.com/vuejs/vue/issues/7017)