@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/watcheffect-flush-post-for-refs.md

@@ -0,0 +1,176 @@
+---
+title: Use flush post for watchEffect with Template Refs
+impact: MEDIUM
+impactDescription: Default watchEffect runs before DOM updates, causing refs to be out of sync
+type: gotcha
+tags: [vue3, watchEffect, template-refs, flush, dom-timing]
+---
+
+# Use flush post for watchEffect with Template Refs
+
+**Impact: MEDIUM** - By default, `watchEffect` runs before the DOM is updated. When watching template refs, this means the effect may run with stale or null ref values. Use `flush: 'post'` to ensure the effect runs after DOM updates when refs are current.
+
+This timing issue is particularly confusing because the watcher runs, but the ref doesn't yet reflect the current DOM state.
+
+## Task Checklist
+
+- [ ] Use `{ flush: 'post' }` when watchEffect accesses template refs
+- [ ] Alternatively, use `watchPostEffect` helper for cleaner syntax
+- [ ] Still include null checks as refs can be unmounted
+- [ ] Consider using `watch` with explicit ref watching instead
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref, watchEffect } from 'vue'
+
+const inputEl = ref(null)
+const text = ref('')
+
+// WRONG: Runs BEFORE DOM update - ref may be null or stale
+watchEffect(() => {
+  // On first run: inputEl.value is null (DOM not rendered yet)
+  // On updates: May reference old element state
+  if (inputEl.value) {
+    console.log('Input value:', inputEl.value.value) // Stale!
+    inputEl.value.focus()
+  }
+})
+</script>
+
+<template>
+  <input ref="inputEl" v-model="text" />
+</template>
+```
+
+```vue
+<script setup>
+import { ref, watchEffect } from 'vue'
+
+const items = ref([1, 2, 3])
+const itemRefs = ref([])
+
+// WRONG: Refs array not yet populated when this runs
+watchEffect(() => {
+  console.log('Number of refs:', itemRefs.value.length) // Always 0!
+})
+</script>
+
+<template>
+  <div v-for="item in items" :key="item" :ref="el => itemRefs.value.push(el)">
+    {{ item }}
+  </div>
+</template>
+```
+
+**Correct:**
+```vue
+<script setup>
+import { ref, watchEffect } from 'vue'
+
+const inputEl = ref(null)
+const text = ref('')
+
+// CORRECT: flush: 'post' runs AFTER DOM update
+watchEffect(() => {
+  if (inputEl.value) {
+    console.log('Input value:', inputEl.value.value) // Current!
+    inputEl.value.focus()
+  }
+}, { flush: 'post' })
+</script>
+
+<template>
+  <input ref="inputEl" v-model="text" />
+</template>
+```
+
+```vue
+<script setup>
+import { ref, watchPostEffect } from 'vue'
+
+const inputEl = ref(null)
+const showInput = ref(true)
+
+// CORRECT: watchPostEffect is shorthand for flush: 'post'
+watchPostEffect(() => {
+  if (inputEl.value) {
+    inputEl.value.focus()
+  }
+})
+</script>
+
+<template>
+  <input v-if="showInput" ref="inputEl" />
+</template>
+```
+
+```vue
+<script setup>
+import { ref, watch, onMounted } from 'vue'
+
+const inputEl = ref(null)
+
+// ALTERNATIVE: Use watch on the ref directly
+watch(inputEl, (el) => {
+  if (el) {
+    el.focus()
+  }
+}, { flush: 'post' })
+
+// ALTERNATIVE: For one-time setup, onMounted is sufficient
+onMounted(() => {
+  inputEl.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="inputEl" />
+</template>
+```
+
+```vue
+<script setup>
+import { useTemplateRef, watchPostEffect } from 'vue'
+
+// Vue 3.5+ with useTemplateRef
+const input = useTemplateRef('my-input')
+
+// CORRECT: watchPostEffect with useTemplateRef
+watchPostEffect(() => {
+  input.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="my-input" />
+</template>
+```
+
+## Flush Options Explained
+
+```javascript
+// Default: 'pre' - runs before DOM update
+watchEffect(() => { ... }) // Same as { flush: 'pre' }
+
+// 'post' - runs after DOM update (use for refs)
+watchEffect(() => { ... }, { flush: 'post' })
+watchPostEffect(() => { ... }) // Shorthand
+
+// 'sync' - runs synchronously (rarely needed, can cause issues)
+watchEffect(() => { ... }, { flush: 'sync' })
+watchSyncEffect(() => { ... }) // Shorthand
+```
+
+## When to Use Each Flush Mode
+
+| Scenario | Recommended Flush |
+|----------|-------------------|
+| Accessing template refs | `post` |
+| Reading updated DOM | `post` |
+| Triggering before render | `pre` (default) |
+| Performance-critical sync updates | `sync` (with caution) |
+
+## Reference
+- [Vue.js Watchers - Callback Flush Timing](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing)
+- [Vue.js watchEffect API](https://vuejs.org/api/reactivity-core.html#watcheffect)

package/skills/vue-jsx-best-practices/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: vue-jsx-best-practices
+description: JSX syntax in Vue (e.g., class vs className, JSX plugin config).
+version: 2.0.0
+license: MIT
+author: github.com/Pythoughts-labs
+---
+
+Vue JSX best practices and differences from React JSX.
+
+### JSX
+- Migrating React JSX code to Vue or getting attribute type errors → See [render-function-jsx-vue-vs-react](reference/render-function-jsx-vue-vs-react.md)

package/skills/vue-jsx-best-practices/reference/render-function-jsx-vue-vs-react.md

@@ -0,0 +1,141 @@
+---
+title: Vue JSX Uses HTML Attributes Not React Conventions
+impact: MEDIUM
+impactDescription: Using className or htmlFor in Vue JSX causes TypeScript errors and inconsistent code style
+type: gotcha
+tags: [vue3, jsx, tsx, render-function]
+---
+
+# Vue JSX Uses HTML Attributes Not React Conventions
+
+**Impact: MEDIUM** - Vue's JSX transform uses standard HTML attribute names (`class`, `for`) instead of React's JavaScript-friendly names (`className`, `htmlFor`). With proper TypeScript configuration, using React conventions like `className` or `htmlFor` will produce TypeScript errors, which is good for catching these inconsistencies early. Note that Vue's runtime is lenient and will actually convert these attributes correctly, but using HTML attributes is the recommended practice for consistency with Vue templates and proper type safety.
+
+When writing JSX in Vue, use the same attribute names you would use in regular HTML templates. This is a fundamental difference from React's JSX where `class` and `for` are reserved JavaScript keywords.
+
+## Task Checklist
+
+- [ ] Use `class` instead of `className` in Vue JSX
+- [ ] Use `for` instead of `htmlFor` in Vue JSX
+- [ ] Use standard HTML event names with `on` prefix (onClick, onInput)
+- [ ] When migrating React components to Vue, update all attribute names
+- [ ] Configure TypeScript properly for Vue JSX type inference
+
+**Incorrect (React-style):**
+```jsx
+// AVOID: React conventions cause TypeScript errors in Vue JSX
+// (Vue runtime is lenient and converts these, but types don't allow them)
+export default {
+  setup() {
+    return () => (
+      <div className="container">
+        <label htmlFor="email">Email:</label>
+        <input id="email" className="input-field" />
+      </div>
+    )
+  }
+}
+```
+
+```tsx
+// AVOID: TypeScript will reject className/htmlFor with Vue's JSX types
+const Button = () => (
+  <button
+    className="btn btn-primary"  // TS error: Property 'className' does not exist
+    htmlFor="form"               // TS error: Property 'htmlFor' does not exist
+  >
+    Submit
+  </button>
+)
+```
+
+**Correct (Vue-style):**
+```jsx
+// CORRECT: Use standard HTML attributes
+export default {
+  setup() {
+    return () => (
+      <div class="container">
+        <label for="email">Email:</label>
+        <input id="email" class="input-field" />
+      </div>
+    )
+  }
+}
+```
+
+```tsx
+// CORRECT: Vue TSX with HTML attributes
+const Button = () => (
+  <button
+    class="btn btn-primary"
+  >
+    Submit
+  </button>
+)
+```
+
+## TypeScript Configuration for Vue JSX
+
+To enable proper type inference and IntelliSense for Vue JSX/TSX, configure your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "jsxImportSource": "vue"
+  }
+}
+```
+
+Starting from Vue 3.4, Vue no longer implicitly registers the global JSX namespace, so `jsxImportSource` is required for TypeScript to use Vue's JSX type definitions.
+
+## Vite Configuration
+
+For Vite projects, ensure you have the JSX plugin configured in `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import vueJsx from '@vitejs/plugin-vue-jsx'
+
+export default defineConfig({
+  plugins: [vue(), vueJsx()]
+})
+```
+
+## Other Attribute Differences
+
+| React JSX | Vue JSX | HTML |
+|-----------|---------|------|
+| className | class | class |
+| htmlFor | for | for |
+| onChange | onInput (for live updates) | oninput |
+| tabIndex | tabindex | tabindex |
+| readOnly | readonly | readonly |
+
+## Event Handling in Vue JSX
+
+```jsx
+// Vue JSX event handling
+export default {
+  setup() {
+    const handleClick = () => console.log('clicked')
+    const handleInput = (e) => console.log(e.target.value)
+
+    return () => (
+      <div>
+        <button onClick={handleClick}>Click</button>
+        <input onInput={handleInput} />
+
+        {/* Event modifiers via helper */}
+        <div onClick={withModifiers(handleClick, ['self'])}>
+          Only triggers on self
+        </div>
+      </div>
+    )
+  }
+}
+```
+
+## Reference
+- [Vue.js JSX and TSX](https://vuejs.org/guide/extras/render-function.html#jsx-tsx)

package/skills/vue-options-api-best-practices/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: vue-options-api-best-practices
+description: "Vue 3 Options API style (data(), methods, this context). Each reference shows Options API solution only."
+version: 2.0.0
+license: MIT
+author: github.com/Pythoughts-labs
+---
+
+Vue.js Options API best practices, TypeScript integration, and common gotchas.
+
+### TypeScript
+- Need to enable TypeScript type inference for component properties → See [ts-options-api-use-definecomponent](reference/ts-options-api-use-definecomponent.md)
+- Enabling type safety for Options API this context → See [ts-strict-mode-options-api](reference/ts-strict-mode-options-api.md)
+- Using old TypeScript versions with prop validators → See [ts-options-api-arrow-functions-validators](reference/ts-options-api-arrow-functions-validators.md)
+- Event handler parameters need proper type safety → See [ts-options-api-type-event-handlers](reference/ts-options-api-type-event-handlers.md)
+- Need to type object or array props with interfaces → See [ts-options-api-proptype-complex-types](reference/ts-options-api-proptype-complex-types.md)
+- Injected properties missing TypeScript types completely → See [ts-options-api-provide-inject-limitations](reference/ts-options-api-provide-inject-limitations.md)
+- Complex computed properties lack clear type documentation → See [ts-options-api-computed-return-types](reference/ts-options-api-computed-return-types.md)
+
+### Methods & Lifecycle
+- Methods aren't binding to component instance context → See [no-arrow-functions-in-methods](reference/no-arrow-functions-in-methods.md)
+- Lifecycle hooks losing access to component data → See [no-arrow-functions-in-lifecycle-hooks](reference/no-arrow-functions-in-lifecycle-hooks.md)
+- Debounced functions sharing state across component instances → See [stateful-methods-lifecycle](reference/stateful-methods-lifecycle.md)

package/skills/vue-options-api-best-practices/reference/no-arrow-functions-in-lifecycle-hooks.md

@@ -0,0 +1,95 @@
+---
+title: Never Use Arrow Functions for Options API Lifecycle Hooks
+impact: HIGH
+impactDescription: Arrow functions in lifecycle hooks break `this` binding to component instance
+type: capability
+tags: [vue3, vue2, options-api, lifecycle, arrow-functions, this-binding, mounted, created]
+---
+
+# Never Use Arrow Functions for Options API Lifecycle Hooks
+
+**Impact: HIGH** - Using arrow functions for lifecycle hooks in the Options API prevents Vue from binding `this` to the component instance. This causes `this` to be `undefined` or reference the wrong context, leading to runtime errors when accessing component data, methods, or other properties.
+
+Arrow functions lexically bind `this` from their enclosing scope. Vue's Options API lifecycle hooks (created, mounted, updated, unmounted, etc.) require regular functions so Vue can set `this` to the component instance at runtime.
+
+## Task Checklist
+
+- [ ] Always use regular function syntax for Options API lifecycle hooks
+- [ ] Use ES6 method shorthand (preferred) for cleaner code
+- [ ] Arrow functions ARE allowed inside lifecycle hooks for callbacks
+
+**Incorrect:**
+```javascript
+export default {
+  data() {
+    return { message: 'Hello' }
+  },
+  // WRONG: Arrow function - `this` will be undefined
+  created: () => {
+    console.log(this.message) // Error: Cannot read property 'message' of undefined
+  },
+  // WRONG: Arrow function for mounted
+  mounted: () => {
+    this.initializePlugin() // Error: this.initializePlugin is not a function
+  },
+  // WRONG: Arrow function for beforeUnmount
+  beforeUnmount: () => {
+    this.cleanup() // Will fail!
+  },
+  methods: {
+    initializePlugin() { /* ... */ },
+    cleanup() { /* ... */ }
+  }
+}
+```
+
+**Correct:**
+```javascript
+export default {
+  data() {
+    return { message: 'Hello' }
+  },
+  // CORRECT: ES6 method shorthand (preferred)
+  created() {
+    console.log(this.message) // Works! this refers to component instance
+  },
+  // CORRECT: Regular function expression
+  mounted: function() {
+    this.initializePlugin() // Works!
+  },
+  // CORRECT: Method shorthand
+  beforeUnmount() {
+    this.cleanup() // Works!
+  },
+  methods: {
+    initializePlugin() {
+      // Arrow functions ARE fine for callbacks inside lifecycle hooks
+      this.$nextTick(() => {
+        this.isReady = true // Arrow inherits `this` from mounted
+      })
+    },
+    cleanup() { /* ... */ }
+  }
+}
+```
+
+## All Affected Lifecycle Hooks
+
+The following Options API hooks must NOT use arrow functions:
+- `beforeCreate`
+- `created`
+- `beforeMount`
+- `mounted`
+- `beforeUpdate`
+- `updated`
+- `beforeUnmount` (Vue 3) / `beforeDestroy` (Vue 2)
+- `unmounted` (Vue 3) / `destroyed` (Vue 2)
+- `activated`
+- `deactivated`
+- `errorCaptured`
+- `renderTracked`
+- `renderTriggered`
+
+## Reference
+- [Vue.js Lifecycle Hooks](https://vuejs.org/guide/essentials/lifecycle.html)
+- [Vue.js Options Lifecycle](https://vuejs.org/api/options-lifecycle.html)

package/skills/vue-options-api-best-practices/reference/no-arrow-functions-in-methods.md

@@ -0,0 +1,68 @@
+---
+title: Never Use Arrow Functions in Methods Option
+impact: HIGH
+impactDescription: Arrow functions prevent Vue from binding `this` to the component instance
+type: capability
+tags: [vue3, vue2, options-api, methods, this-binding]
+---
+
+# Never Use Arrow Functions in Methods Option
+
+**Impact: HIGH** - Using arrow functions in the `methods` option causes `this` to be `undefined` or the wrong context, leading to runtime errors when trying to access component data, computed properties, or other methods.
+
+Arrow functions lexically bind `this` from their enclosing scope, not from the object they're defined on. Vue's `methods` option requires regular functions so Vue can bind `this` to the component instance.
+
+## Task Checklist
+
+- [ ] Always use regular function syntax for methods in Options API
+- [ ] If using ES6 shorthand, use method shorthand (preferred)
+- [ ] Arrow functions ARE allowed inside methods for callbacks
+
+**Incorrect:**
+```javascript
+export default {
+  data() {
+    return { count: 0 }
+  },
+  methods: {
+    // WRONG: Arrow function - `this` will be undefined
+    increment: () => {
+      this.count++ // Error: Cannot read property 'count' of undefined
+    },
+    // WRONG: Arrow function assigned to property
+    decrement: () => {
+      this.count--
+    }
+  }
+}
+```
+
+**Correct:**
+```javascript
+export default {
+  data() {
+    return { count: 0 }
+  },
+  methods: {
+    // CORRECT: ES6 method shorthand (preferred)
+    increment() {
+      this.count++ // Works! this refers to component instance
+    },
+    // CORRECT: Traditional function expression
+    decrement: function() {
+      this.count--
+    },
+    // Arrow functions ARE fine for callbacks INSIDE methods
+    fetchData() {
+      fetch('/api/data')
+        .then(response => response.json())
+        .then(data => {
+          this.data = data // Arrow function inherits `this` from fetchData
+        })
+    }
+  }
+}
+```
+
+## Reference
+- [Vue.js Methods - Avoid Arrow Functions](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#methods)

package/skills/vue-options-api-best-practices/reference/stateful-methods-lifecycle.md

@@ -0,0 +1,61 @@
+---
+title: Create Stateful Methods in Lifecycle Hooks
+impact: MEDIUM
+impactDescription: Stateful functions like debounce/throttle in methods are shared across all component instances
+type: capability
+tags: [vue3, options-api, debounce, throttle, lifecycle, cleanup]
+---
+
+# Create Stateful Methods in Lifecycle Hooks
+
+**Impact: MEDIUM** - If you define debounced, throttled, or other stateful functions directly in the `methods` option, all instances of the component share the same function state. This causes race conditions and bugs in lists of components.
+
+When a component is reused (e.g., in v-for), each instance needs its own debounced/throttled function. Define these in the `created()` hook and clean them up in `unmounted()` to prevent memory leaks.
+
+## Task Checklist
+
+- [ ] Never define debounced/throttled functions directly in `methods`
+- [ ] Create stateful functions in `created()` lifecycle hook
+- [ ] Always clean up (cancel timers) in `unmounted()`
+
+**Incorrect:**
+```javascript
+import { debounce } from 'lodash-es'
+
+export default {
+  methods: {
+    // WRONG: All component instances share this debounced function!
+    // If used in a v-for, clicking one button affects all instances
+    handleClick: debounce(function() {
+      this.performSearch()
+    }, 500)
+  }
+}
+```
+
+**Correct:**
+```javascript
+import { debounce } from 'lodash-es'
+
+export default {
+  created() {
+    // CORRECT: Each instance gets its own debounced function
+    this.debouncedSearch = debounce(this.performSearch, 500)
+  },
+  unmounted() {
+    // CORRECT: Clean up to prevent memory leaks and stale calls
+    this.debouncedSearch.cancel()
+  },
+  methods: {
+    handleClick() {
+      this.debouncedSearch()
+    },
+    performSearch() {
+      // Actual search logic
+    }
+  }
+}
+```
+
+## Reference
+- [Vue.js Reactivity Fundamentals - Stateful Methods](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#stateful-methods)