@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-best-practices/references/component-data-flow.md

@@ -0,0 +1,350 @@
+---
+title: Component Data Flow Best Practices
+impact: HIGH
+impactDescription: Clear data flow between components prevents state bugs, stale UI, and brittle coupling
+type: best-practice
+tags: [vue3, props, emits, v-model, provide-inject, data-flow, typescript]
+---
+
+# Component Data Flow Best Practices
+
+**Impact: HIGH** - Vue components stay reliable when data flow is explicit: props go down, events go up, `v-model` handles two-way bindings, and provide/inject supports cross-tree dependencies. Blurring these boundaries leads to stale state, hidden coupling, and hard-to-debug UI.
+
+The main principle of data flow in Vue.js is **Props Down / Events Up**. This is the most maintainable default, and one-way flow scales well.
+
+## Task List
+
+- Treat props as read-only inputs
+- Prefer reactive props destructure for defaults in modern Vue (3.5+), and watch destructured props with a getter
+- Use props/emit for component communication; reserve refs for imperative actions
+- When refs are required for imperative APIs, type them with template refs
+- Emit events instead of mutating parent state directly
+- Use `defineModel` for v-model in modern Vue (3.4+)
+- Handle v-model modifiers deliberately in child components
+- Use symbols for provide/inject keys to avoid props drilling (over ~3 layers)
+- Keep mutations in the provider or expose explicit actions
+- In TypeScript projects, prefer type-based `defineProps`, `defineEmits`, and `InjectionKey`
+
+## Props: One-Way Data Down
+
+Props are inputs. Do not mutate them in the child.
+
+**BAD:**
+```vue
+<script setup>
+const props = defineProps({ count: Number })
+
+function increment() {
+  props.count++
+}
+</script>
+```
+
+**GOOD:**
+
+If state needs to change, emit an event, use `v-model` or create a local copy.
+
+## Reactive Props Destructure (Vue 3.5+)
+
+Since Vue 3.5, variables destructured from `defineProps` stay reactive. Prefer this for declaring defaults: use native JS default syntax instead of `withDefaults`. Destructured props remain read-only.
+
+**BAD (verbose `withDefaults`):**
+```vue
+<script setup lang="ts">
+interface Props {
+  msg?: string
+  labels?: string[]
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  msg: 'hello',
+  labels: () => ['one', 'two']
+})
+</script>
+```
+
+**GOOD (Vue 3.5+):**
+```vue
+<script setup lang="ts">
+interface Props {
+  msg?: string
+  labels?: string[]
+}
+
+// Each instance gets its own copy of mutable defaults — no factory needed
+const { msg = 'hello', labels = ['one', 'two'] } = defineProps<Props>()
+</script>
+```
+
+**Gotcha — watching or passing a destructured prop needs a getter.** A destructured prop is a plain variable, so passing it directly to `watch` (or any function expecting a reactive source) loses reactivity; Vue's compiler warns on this. Wrap it in a getter:
+
+```ts
+// ❌ not reactive — passes a value, not a source
+watch(msg, () => { /* ... */ })
+
+// ✅ getter preserves reactivity
+watch(() => msg, () => { /* ... */ })
+```
+
+## Prefer props/emit over component refs
+
+**BAD:**
+```vue
+<script setup>
+import { ref } from 'vue'
+import UserForm from './UserForm.vue'
+
+const formRef = ref(null)
+
+function submitForm() {
+  if (formRef.value.isValid) {
+    formRef.value.submit()
+  }
+}
+</script>
+
+<template>
+  <UserForm ref="formRef" />
+  <button @click="submitForm">Submit</button>
+</template>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import UserForm from './UserForm.vue'
+
+function handleSubmit(formData) {
+  api.submit(formData)
+}
+</script>
+
+<template>
+  <UserForm @submit="handleSubmit" />
+</template>
+```
+
+## Type component refs when imperative access is required
+
+Prefer props/emits by default. When a parent must call an exposed child method, type the ref explicitly and expose only the intended API from the child with `defineExpose`.
+
+**BAD:**
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import DialogPanel from './DialogPanel.vue'
+
+const panelRef = ref(null)
+
+onMounted(() => {
+  panelRef.value.open()
+})
+</script>
+
+<template>
+  <DialogPanel ref="panelRef" />
+</template>
+```
+
+**GOOD:**
+```vue
+<!-- DialogPanel.vue -->
+<script setup lang="ts">
+function open() {}
+
+defineExpose({ open })
+</script>
+```
+
+```vue
+<!-- Parent.vue -->
+<script setup lang="ts">
+import { onMounted, useTemplateRef } from 'vue'
+import DialogPanel from './DialogPanel.vue'
+
+// Vue 3.5+ with useTemplateRef
+const panelRef = useTemplateRef('panelRef')
+
+// Before Vue 3.5 with manual typing and ref
+// const panelRef = ref<InstanceType<typeof DialogPanel> | null>(null)
+
+onMounted(() => {
+  panelRef.value?.open()
+})
+</script>
+
+<template>
+  <DialogPanel ref="panelRef" />
+</template>
+```
+
+## Emits: Explicit Events Up
+
+Component events do not bubble. If a parent needs to know about an event, re-emit it explicitly.
+
+**BAD:**
+```vue
+<!-- Parent expects "saved" from grandchild, but it won't bubble -->
+<Child @saved="onSaved" />
+```
+
+**GOOD:**
+```vue
+<!-- Child.vue -->
+<script setup>
+const emit = defineEmits(['saved'])
+
+function onGrandchildSaved(payload) {
+  emit('saved', payload)
+}
+</script>
+
+<template>
+  <Grandchild @saved="onGrandchildSaved" />
+</template>
+```
+
+**Event naming:** use kebab-case in templates and camelCase in script:
+```vue
+<script setup>
+const emit = defineEmits(['updateUser'])
+</script>
+
+<template>
+  <ProfileForm @update-user="emit('updateUser', $event)" />
+</template>
+```
+
+## `v-model`: Predictable Two-Way Bindings
+
+Use `defineModel` by default for component bindings and emit updates on input. Only use the `modelValue` + `update:modelValue` pattern if you are on Vue < 3.4.
+
+**BAD:**
+```vue
+<script setup>
+const props = defineProps({ value: String })
+</script>
+
+<template>
+  <input :value="props.value" @input="$emit('input', $event.target.value)" />
+</template>
+```
+
+**GOOD (Vue 3.4+):**
+```vue
+<script setup>
+const model = defineModel({ type: String })
+</script>
+
+<template>
+  <input v-model="model" />
+</template>
+```
+
+**GOOD (Vue < 3.4):**
+```vue
+<script setup>
+const props = defineProps({ modelValue: String })
+const emit = defineEmits(['update:modelValue'])
+</script>
+
+<template>
+  <input
+    :value="props.modelValue"
+    @input="emit('update:modelValue', $event.target.value)"
+  />
+</template>
+```
+
+If you need the updated value immediately after a change, use the input event value or `nextTick` in the parent.
+
+## Provide/Inject: Shared Context Without Prop Drilling
+
+Use provide/inject for cross-tree state, but keep mutations centralized in the provider and expose explicit actions.
+
+**BAD:**
+```vue
+// Provider.vue
+provide('theme', reactive({ dark: false }))
+
+// Consumer.vue
+const theme = inject('theme')
+// Mutating shared state from any depth becomes hard to track
+theme.dark = true
+```
+
+**GOOD:**
+```vue
+// Provider.vue
+const theme = reactive({ dark: false })
+const toggleTheme = () => { theme.dark = !theme.dark }
+
+provide(themeKey, readonly(theme))
+provide(themeActionsKey, { toggleTheme })
+
+// Consumer.vue
+const theme = inject(themeKey)
+const { toggleTheme } = inject(themeActionsKey)
+```
+
+Use symbols for keys to avoid collisions in large apps:
+```ts
+export const themeKey = Symbol('theme')
+export const themeActionsKey = Symbol('theme-actions')
+```
+
+## Use TypeScript Contracts for Public Component APIs
+
+In TypeScript projects, type component boundaries directly with `defineProps`, `defineEmits`, and `InjectionKey` so invalid payloads and mismatched injections fail at compile time.
+
+**BAD:**
+```vue
+<script setup lang="ts">
+import { inject } from 'vue'
+
+const props = defineProps({
+  userId: String
+})
+
+const emit = defineEmits(['save'])
+const settings = inject('settings')
+
+// Payload shape is not checked here
+emit('save', 123)
+
+// Key is string-based and not type-safe
+settings?.theme = 'dark'
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup lang="ts">
+import { inject, provide } from 'vue'
+import type { InjectionKey } from 'vue'
+
+interface Props {
+  userId: string
+}
+
+interface Emits {
+  save: [payload: { id: string; draft: boolean }]
+}
+
+interface Settings {
+  theme: 'light' | 'dark'
+}
+
+const settingsKey: InjectionKey<Settings> = Symbol('settings')
+
+const props = defineProps<Props>()
+const emit = defineEmits<Emits>()
+
+provide(settingsKey, { theme: 'light' })
+
+const settings = inject(settingsKey)
+if (settings) {
+  emit('save', { id: props.userId, draft: false })
+}
+</script>
+```

package/skills/vue-best-practices/references/component-fallthrough-attrs.md

@@ -0,0 +1,174 @@
+---
+title: Component Fallthrough Attributes Best Practices
+impact: MEDIUM
+impactDescription: Incorrect $attrs access and reactivity assumptions can cause undefined values and watchers that never run
+type: best-practice
+tags: [vue3, attrs, fallthrough-attributes, composition-api, reactivity]
+---
+
+# Component Fallthrough Attributes Best Practices
+
+**Impact: MEDIUM** - Fallthrough attributes are straightforward once you follow Vue's conventions: hyphenated names use bracket notation, listener keys are camelCase `onX`, and `useAttrs()` is current-but-not-reactive.
+
+## Task List
+
+- Access hyphenated attribute names with bracket notation (for example `attrs['data-testid']`)
+- Access event listeners with camelCase `onX` keys (for example `attrs.onClick`)
+- Do not `watch()` values returned from `useAttrs()`; those watchers do not trigger on attr changes
+- Use `onUpdated()` for attr-driven side effects
+- Promote frequently observed attrs to props when reactive observation is required
+
+## Access Attribute and Listener Keys Correctly
+
+Hyphenated attribute names preserve their original casing in JavaScript, so dot notation does not work for keys that include `-`.
+
+**BAD:**
+```vue
+<script setup>
+import { useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+console.log(attrs.data-testid)  // Syntax error
+console.log(attrs.dataTestid)   // undefined for data-testid
+console.log(attrs['on-click'])  // undefined
+console.log(attrs['@click'])    // undefined
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import { useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+console.log(attrs['data-testid'])
+console.log(attrs['aria-label'])
+console.log(attrs['foo-bar'])
+
+console.log(attrs.onClick)
+console.log(attrs.onCustomEvent)
+console.log(attrs.onMouseEnter)
+</script>
+```
+
+### Naming Reference
+
+| Parent Usage | Access in `attrs` |
+|--------------|-------------------|
+| `class="foo"` | `attrs.class` |
+| `data-id="123"` | `attrs['data-id']` |
+| `aria-label="..."` | `attrs['aria-label']` |
+| `foo-bar="baz"` | `attrs['foo-bar']` |
+| `@click="fn"` | `attrs.onClick` |
+| `@custom-event="fn"` | `attrs.onCustomEvent` |
+| `@update:modelValue="fn"` | `attrs['onUpdate:modelValue']` |
+
+## `useAttrs()` Is Not Reactive
+
+`useAttrs()` always reflects the latest values, but it is intentionally not reactive for watcher tracking.
+
+**BAD:**
+```vue
+<script setup>
+import { watch, watchEffect, useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+watch(
+  () => attrs.someAttr,
+  (newValue) => {
+    console.log('Changed:', newValue) // Never runs on attr changes
+  }
+)
+
+watchEffect(() => {
+  console.log(attrs.class) // Runs on setup, not on attr updates
+})
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import { onUpdated, useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+onUpdated(() => {
+  console.log('Latest attrs:', attrs)
+})
+</script>
+```
+
+**GOOD:**
+```vue
+<script setup>
+import { watch } from 'vue'
+
+const props = defineProps({
+  someAttr: String
+})
+
+watch(
+  () => props.someAttr,
+  (newValue) => {
+    console.log('Changed:', newValue)
+  }
+)
+</script>
+```
+
+## Common Patterns
+
+### Check for optional attrs safely
+
+```vue
+<script setup>
+import { computed, useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+const hasTestId = computed(() => 'data-testid' in attrs)
+const ariaLabel = computed(() => attrs['aria-label'] ?? 'Default label')
+</script>
+```
+
+### Forward listeners after internal logic
+
+```vue
+<script setup>
+import { useAttrs } from 'vue'
+
+defineOptions({ inheritAttrs: false })
+
+const attrs = useAttrs()
+
+function handleClick(event) {
+  console.log('Internal handling first')
+  attrs.onClick?.(event)
+}
+</script>
+
+<template>
+  <button @click="handleClick">
+    <slot />
+  </button>
+</template>
+```
+
+## TypeScript Notes
+
+`useAttrs()` is typed as `Record<string, unknown>`, so cast individual keys when needed.
+
+```vue
+<script setup lang="ts">
+import { useAttrs } from 'vue'
+
+const attrs = useAttrs()
+
+const testId = attrs['data-testid'] as string | undefined
+const onClick = attrs.onClick as ((event: MouseEvent) => void) | undefined
+</script>
+```

package/skills/vue-best-practices/references/component-keep-alive.md

@@ -0,0 +1,137 @@
+---
+title: KeepAlive Component Best Practices
+impact: HIGH
+impactDescription: KeepAlive caches component instances; misuse causes stale data, memory growth, or unexpected lifecycle behavior
+type: best-practice
+tags: [vue3, keepalive, cache, performance, router, dynamic-components]
+---
+
+# KeepAlive Component Best Practices
+
+**Impact: HIGH** - `<KeepAlive>` caches component instances instead of destroying them. Use it to preserve state across switches, but manage cache size and freshness explicitly to avoid memory growth or stale UI.
+
+## Task List
+
+- Use KeepAlive only where state preservation improves UX
+- Set a reasonable `max` to cap cache size
+- Declare component names for include/exclude matching
+- Use `onActivated`/`onDeactivated` for cache-aware logic
+- Decide how and when cached views refresh their data
+- Avoid caching memory-heavy or security-sensitive views
+
+## When to Use KeepAlive
+
+Use KeepAlive when switching between views where state should persist (tabs, multi-step forms, dashboards). Avoid it when each visit should start fresh.
+
+**BAD:**
+```vue
+<template>
+  <!-- State resets on every switch -->
+  <component :is="currentTab" />
+</template>
+```
+
+**GOOD:**
+```vue
+<template>
+  <!-- State preserved between switches -->
+  <KeepAlive>
+    <component :is="currentTab" />
+  </KeepAlive>
+</template>
+```
+
+## When NOT to Use KeepAlive
+
+- Search or filter pages where users expect fresh results
+- Memory-heavy components (maps, large tables, media players)
+- Sensitive flows where data must be cleared on exit
+- Components with heavy background activity you cannot pause
+
+## Limit and Control the Cache
+
+Always cap cache size with `max` and restrict caching to specific components when possible.
+
+```vue
+<template>
+  <KeepAlive :max="5" include="Dashboard,Settings">
+    <component :is="currentView" />
+  </KeepAlive>
+</template>
+```
+
+## Ensure Component Names Match include/exclude
+
+`include` and `exclude` match the component `name` option. Explicitly set names for reliable caching.
+
+```vue
+<!-- TabA.vue -->
+<script setup>
+defineOptions({ name: 'TabA' })
+</script>
+```
+
+```vue
+<template>
+  <KeepAlive include="TabA,TabB">
+    <component :is="currentTab" />
+  </KeepAlive>
+</template>
+```
+
+## Cache Invalidation Strategies
+
+Vue 3 has no direct API to remove a specific cached instance. Use keys or dynamic include/exclude to force refreshes.
+
+```vue
+<script setup>
+import { ref, reactive } from 'vue'
+
+const currentView = ref('Dashboard')
+const viewKeys = reactive({ Dashboard: 0, Settings: 0 })
+
+function invalidateCache(view) {
+  viewKeys[view]++
+}
+</script>
+
+<template>
+  <KeepAlive>
+    <component :is="currentView" :key="`${currentView}-${viewKeys[currentView]}`" />
+  </KeepAlive>
+</template>
+```
+
+## Lifecycle Hooks for Cached Components
+
+Cached components are not destroyed on switch. Use activation hooks for refresh and cleanup.
+
+```vue
+<script setup>
+import { onActivated, onDeactivated } from 'vue'
+
+onActivated(() => {
+  refreshData()
+})
+
+onDeactivated(() => {
+  pauseTimers()
+})
+</script>
+```
+
+## Router Caching and Freshness
+
+Decide whether navigation should show cached state or a fresh view. A common pattern is to key by route when params change.
+
+```vue
+<template>
+  <router-view v-slot="{ Component, route }">
+    <KeepAlive>
+      <component :is="Component" :key="route.fullPath" />
+    </KeepAlive>
+  </router-view>
+</template>
+```
+
+If you want cache reuse but fresh data, refresh in `onActivated` and compare query/params before fetching.