@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/plugin-install-before-mount.md

@@ -0,0 +1,124 @@
+# Install Plugins Before Mounting the App
+
+## Rule
+
+All plugins must be installed using `app.use()` BEFORE calling `app.mount()`. Installing plugins after the app is mounted can lead to reactivity issues, missing dependencies, and unexpected behavior.
+
+## Why This Matters
+
+1. **Hidden dependencies**: Components may render before plugins they depend on are available, causing runtime errors.
+
+2. **Reactivity issues**: Late plugin installation can cause subtle reactivity problems where provided values aren't properly reactive.
+
+3. **Initialization order**: Many plugins (like vue-router, pinia) need to set up state before any component renders.
+
+4. **Ecosystem complexity**: Adding plugins after mount can cause issues with Vue's internal ecosystem and hydration in SSR scenarios.
+
+## Bad Practice
+
+```typescript
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+import i18nPlugin from './plugins/i18n'
+
+const app = createApp(App)
+
+// Mounting first - plugins not yet available!
+app.mount('#app')
+
+// Installing after mount - TOO LATE!
+app.use(router)
+app.use(i18nPlugin, { locale: 'en' })
+```
+
+## Good Practice
+
+```typescript
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+import { createPinia } from 'pinia'
+import i18nPlugin from './plugins/i18n'
+
+const app = createApp(App)
+
+// Install all plugins BEFORE mounting
+app.use(createPinia())
+app.use(router)
+app.use(i18nPlugin, { locale: 'en' })
+
+// Mount LAST
+app.mount('#app')
+```
+
+## Plugin Installation Order
+
+The order of `app.use()` calls can matter when plugins depend on each other:
+
+```typescript
+const app = createApp(App)
+
+// 1. State management first (other plugins might need it)
+app.use(createPinia())
+
+// 2. Router (may depend on state)
+app.use(router)
+
+// 3. Other plugins (may depend on router or state)
+app.use(authPlugin)
+app.use(i18nPlugin, { locale: 'en' })
+
+// 4. Mount last
+app.mount('#app')
+```
+
+## Async Plugin Installation
+
+If you need to perform async operations before mounting:
+
+```typescript
+import { createApp } from 'vue'
+import App from './App.vue'
+import { loadPlugins } from './plugins'
+
+async function bootstrap() {
+  const app = createApp(App)
+
+  // Await async plugin setup
+  const i18nPlugin = await loadI18nMessages()
+
+  // Install all plugins
+  app.use(i18nPlugin)
+
+  // Mount after everything is ready
+  app.mount('#app')
+}
+
+bootstrap()
+```
+
+## Duplicate Installation Protection
+
+Vue's `app.use()` automatically prevents duplicate plugin installation:
+
+```typescript
+app.use(myPlugin)
+app.use(myPlugin) // This second call is ignored - no double installation
+
+// This is handled internally by Vue, providing a safety net
+```
+
+## Common Symptoms of Late Plugin Installation
+
+- `inject()` returns `undefined` unexpectedly
+- Router navigation guards not firing
+- Store state not reactive
+- Template errors about undefined global properties
+- Hydration mismatches in SSR
+
+## References
+
+- [Vue.js Plugins Documentation](https://vuejs.org/guide/reusability/plugins.html)
+- [Vue.js Application API](https://vuejs.org/api/application.html)
+- [Vue 3 Migration Guide - Global API](https://v3-migration.vuejs.org/breaking-changes/global-api.html)

package/skills/vue-debug-guides/reference/plugin-prefer-provide-inject-over-global-properties.md

@@ -0,0 +1,120 @@
+# Prefer provide/inject Over Global Properties in Plugins
+
+## Rule
+
+When creating Vue plugins, prefer using `app.provide()` to make plugin functionality available to components instead of attaching properties to `app.config.globalProperties`.
+
+## Why This Matters
+
+1. **globalProperties don't work in setup()**: Properties attached to `globalProperties` are only accessible via `this` in Options API. They are NOT available in the Composition API's `setup()` function.
+
+2. **Type safety**: `provide/inject` integrates better with TypeScript and requires less type augmentation boilerplate.
+
+3. **Testability**: Injected dependencies are easier to mock in tests compared to global properties.
+
+4. **Code clarity**: Explicit `inject()` calls make dependencies visible, while global properties can appear "magic".
+
+5. **Scoping**: `provide/inject` follows Vue's component hierarchy, making it easier to provide different values to different parts of your app.
+
+## Bad Practice
+
+```typescript
+// plugins/i18n.ts
+export default {
+  install(app, options) {
+    // Attaching to globalProperties - only works with Options API
+    app.config.globalProperties.$translate = (key: string) => {
+      return key.split('.').reduce((o, i) => o?.[i], options)
+    }
+  }
+}
+
+// In component - requires type augmentation for TypeScript
+// Also DOES NOT work in <script setup>
+export default {
+  mounted() {
+    console.log(this.$translate('greeting.hello'))
+  }
+}
+```
+
+## Good Practice
+
+```typescript
+// plugins/i18n.ts
+import type { InjectionKey, App } from 'vue'
+
+export interface I18nOptions {
+  [key: string]: string | I18nOptions
+}
+
+export interface I18n {
+  translate: (key: string) => string
+  options: I18nOptions
+}
+
+export const i18nKey: InjectionKey<I18n> = Symbol('i18n')
+
+export default {
+  install(app: App, options: I18nOptions) {
+    const translate = (key: string): string => {
+      return key.split('.').reduce((o, i) => o?.[i], options) as string ?? key
+    }
+
+    // Use provide for Composition API compatibility
+    app.provide(i18nKey, { translate, options })
+  }
+}
+
+// In component - works in setup() and has full type safety
+<script setup lang="ts">
+import { inject } from 'vue'
+import { i18nKey } from '@/plugins/i18n'
+
+const i18n = inject(i18nKey)
+console.log(i18n?.translate('greeting.hello'))
+</script>
+```
+
+## Hybrid Approach
+
+If you must support both APIs (e.g., for backwards compatibility), provide both:
+
+```typescript
+export default {
+  install(app: App, options: I18nOptions) {
+    const i18n = {
+      translate: (key: string) => /* ... */
+    }
+
+    // For Composition API
+    app.provide(i18nKey, i18n)
+
+    // For Options API (use sparingly)
+    app.config.globalProperties.$i18n = i18n
+  }
+}
+```
+
+## TypeScript Type Augmentation (if using globalProperties)
+
+If you must use globalProperties, you need proper type augmentation:
+
+```typescript
+// types/vue.d.ts
+export {}
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $translate: (key: string) => string
+  }
+}
+```
+
+**Important**: The file MUST contain `export {}` or another top-level export/import. Without it, the augmentation will OVERWRITE types instead of augmenting them.
+
+## References
+
+- [Vue.js Plugins Documentation](https://vuejs.org/guide/reusability/plugins.html)
+- [Vue.js Provide/Inject](https://vuejs.org/guide/components/provide-inject.html)
+- [TypeScript with Options API](https://vuejs.org/guide/typescript/options-api.html)

package/skills/vue-debug-guides/reference/plugin-typescript-type-augmentation.md

@@ -0,0 +1,157 @@
+# Proper TypeScript Type Augmentation for Plugins
+
+## Rule
+
+When creating Vue plugins that add global properties, you MUST properly augment TypeScript types. The augmentation file MUST contain at least one top-level `import` or `export` statement to be treated as a module.
+
+## Why This Matters
+
+1. **Without module syntax, types are overwritten**: If your augmentation file isn't a module, it will OVERWRITE Vue's types instead of augmenting them, breaking type checking for the entire application.
+
+2. **Type safety**: Proper augmentation enables autocomplete and type checking for plugin-provided properties.
+
+3. **IDE support**: Developers get proper IntelliSense for global properties like `this.$translate`.
+
+4. **Error prevention**: Catch typos and incorrect usage at compile time rather than runtime.
+
+## Critical Rule: Module Syntax Required
+
+```typescript
+// BAD - This OVERWRITES Vue types instead of augmenting!
+// types/vue.d.ts
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $translate: (key: string) => string
+  }
+}
+
+// GOOD - The export {} makes this a module, so it AUGMENTS types
+// types/vue.d.ts
+export {}  // This line is CRITICAL!
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $translate: (key: string) => string
+  }
+}
+```
+
+## Complete Plugin Type Augmentation Example
+
+```typescript
+// plugins/i18n.ts
+import type { App, InjectionKey } from 'vue'
+
+export interface I18nOptions {
+  locale: string
+  messages: Record<string, Record<string, string>>
+}
+
+export interface I18nInstance {
+  translate: (key: string) => string
+  locale: string
+}
+
+export const i18nInjectionKey: InjectionKey<I18nInstance> = Symbol('i18n')
+
+export function createI18n(options: I18nOptions) {
+  const i18n: I18nInstance = {
+    translate(key: string) {
+      return options.messages[options.locale]?.[key] ?? key
+    },
+    locale: options.locale
+  }
+
+  return {
+    install(app: App) {
+      // For Composition API
+      app.provide(i18nInjectionKey, i18n)
+
+      // For Options API / templates
+      app.config.globalProperties.$t = i18n.translate
+      app.config.globalProperties.$i18n = i18n
+    }
+  }
+}
+
+// types/i18n.d.ts (or in the same file after export)
+export {}
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $t: (key: string) => string
+    $i18n: I18nInstance
+  }
+}
+```
+
+## Alternative: Augment @vue/runtime-core
+
+Some plugins augment `@vue/runtime-core` instead of `vue`:
+
+```typescript
+// types/global.d.ts
+export {}
+
+declare module '@vue/runtime-core' {
+  interface ComponentCustomProperties {
+    $myPlugin: MyPluginInstance
+  }
+}
+```
+
+Both approaches work, but `'vue'` is more common in application code.
+
+## Ensure tsconfig.json Includes the Declaration File
+
+```json
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.vue",
+    "types/**/*.d.ts"  // Include your declaration files
+  ]
+}
+```
+
+## For Library Authors: package.json Types Field
+
+If publishing a plugin as a package:
+
+```json
+{
+  "name": "my-vue-plugin",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  }
+}
+```
+
+## Common Errors and Solutions
+
+### Error: Property '$xyz' does not exist on type
+
+1. Check that your `.d.ts` file has `export {}` or an import statement
+2. Verify the file is included in `tsconfig.json`
+3. Restart your TypeScript language server (VS Code: Cmd+Shift+P > "Restart TS Server")
+
+### Error: Types work in some components but not others
+
+This often happens when using Vetur instead of Volar. If you're on Vue 3, switch to Volar (Vue - Official extension).
+
+### Error in Options API but not Composition API
+
+Global properties on `this` require proper augmentation of `ComponentCustomProperties`. The Composition API uses `inject()` which is typed separately.
+
+## References
+
+- [Vue.js TypeScript with Options API](https://vuejs.org/guide/typescript/options-api.html)
+- [TypeScript Module Augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation)
+- [Vue.js Plugins Documentation](https://vuejs.org/guide/reusability/plugins.html)

package/skills/vue-debug-guides/reference/prop-defineprops-scope-limitation.md

@@ -0,0 +1,161 @@
+---
+title: defineProps Cannot Access Variables from script setup
+impact: MEDIUM
+impactDescription: Variables declared in script setup are not accessible inside defineProps arguments
+type: gotcha
+tags: [vue3, props, script-setup, defineProps, compiler]
+---
+
+# defineProps Cannot Access Variables from script setup
+
+**Impact: MEDIUM** - Code inside the `defineProps()` argument cannot access other variables declared in `<script setup>`. The entire expression is moved to an outer function scope when compiled, making local variables inaccessible.
+
+This commonly surprises developers trying to use imported constants or computed validation logic.
+
+## Task Checklist
+
+- [ ] Define validation constants outside `<script setup>` or in a separate file
+- [ ] Import constants before using them in defineProps
+- [ ] Use external type definitions for TypeScript props
+- [ ] For dynamic validation, use watchers instead of prop validators
+
+**Incorrect:**
+```vue
+<script setup>
+import { ref } from 'vue'
+
+// These are in <script setup> scope
+const VALID_SIZES = ['sm', 'md', 'lg']
+const maxLength = ref(100)
+
+defineProps({
+  size: {
+    type: String,
+    // WRONG: VALID_SIZES is not accessible here
+    validator: (v) => VALID_SIZES.includes(v)  // ReferenceError!
+  },
+  name: {
+    type: String,
+    // WRONG: Cannot access refs
+    validator: (v) => v.length <= maxLength.value  // ReferenceError!
+  }
+})
+</script>
+```
+
+**Correct:**
+```vue
+<script>
+// Define constants in regular <script> block (module scope)
+export const VALID_SIZES = ['sm', 'md', 'lg']
+export const MAX_LENGTH = 100
+</script>
+
+<script setup>
+// Now accessible in defineProps
+defineProps({
+  size: {
+    type: String,
+    validator: (v) => VALID_SIZES.includes(v)  // Works!
+  },
+  name: {
+    type: String,
+    validator: (v) => v.length <= MAX_LENGTH  // Works!
+  }
+})
+</script>
+```
+
+## Pattern: Import from External File
+
+```javascript
+// validation.js
+export const VALID_SIZES = ['sm', 'md', 'lg']
+export const VALID_COLORS = ['red', 'blue', 'green']
+export const sizeValidator = (v) => VALID_SIZES.includes(v)
+```
+
+```vue
+<script setup>
+import { VALID_SIZES, VALID_COLORS, sizeValidator } from './validation'
+
+// Imported values ARE accessible
+defineProps({
+  size: {
+    type: String,
+    validator: sizeValidator
+  },
+  color: {
+    type: String,
+    validator: (v) => VALID_COLORS.includes(v)
+  }
+})
+</script>
+```
+
+## Pattern: Dual Script Blocks
+
+```vue
+<script>
+// Regular script for module-level declarations
+const options = {
+  themes: ['light', 'dark', 'system'],
+  defaults: {
+    theme: 'light',
+    size: 'md'
+  }
+}
+</script>
+
+<script setup>
+// options is accessible here
+const props = defineProps({
+  theme: {
+    type: String,
+    default: options.defaults.theme,
+    validator: (v) => options.themes.includes(v)
+  }
+})
+</script>
+```
+
+## TypeScript: External Type Definitions
+
+```typescript
+// types.ts
+export interface UserProps {
+  name: string
+  email: string
+  age?: number
+}
+```
+
+```vue
+<script setup lang="ts">
+import type { UserProps } from './types'
+
+// Type imports work fine
+const props = defineProps<UserProps>()
+</script>
+```
+
+## Why This Happens
+
+Vue's compiler transforms `<script setup>` code. The `defineProps()` call is extracted and moved to component options at compile time, before the setup function runs:
+
+```javascript
+// Your code:
+const MY_CONST = 'value'
+defineProps({ prop: { default: MY_CONST } })
+
+// Compiled (simplified):
+export default {
+  props: { prop: { default: MY_CONST } },  // MY_CONST doesn't exist here!
+  setup() {
+    const MY_CONST = 'value'  // Defined too late
+  }
+}
+```
+
+## Reference
+- [Vue.js Script Setup - defineProps](https://vuejs.org/api/sfc-script-setup.html#defineprops-defineemits)