@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/slot-v-slot-on-components-or-templates-only.md

@@ -0,0 +1,122 @@
+---
+title: v-slot Can Only Be Used on Components or Template Tags
+impact: HIGH
+impactDescription: Using v-slot on HTML elements causes compilation errors
+type: gotcha
+tags: [vue3, slots, v-slot, compilation-error, common-mistake]
+---
+
+# v-slot Can Only Be Used on Components or Template Tags
+
+**Impact: HIGH** - The `v-slot` directive (and its shorthand `#`) can only be used on Vue components or `<template>` tags. Using it on native HTML elements like `<div>` or `<span>` causes a Vue compilation error.
+
+## Task Checklist
+
+- [ ] Only use `v-slot` on component elements or `<template>` tags
+- [ ] When using default scoped slot shorthand, apply to the component itself
+- [ ] For named slots, always use `<template #name>` syntax
+
+**Incorrect:**
+```vue
+<template>
+  <!-- BAD: v-slot on a native HTML element -->
+  <div v-slot:header>
+    <h1>Title</h1>
+  </div>
+
+  <!-- BAD: Shorthand on HTML element -->
+  <span #default="{ item }">
+    {{ item.name }}
+  </span>
+
+  <!-- BAD: v-slot inside a plain HTML element -->
+  <div>
+    <p v-slot:content>Some text</p>
+  </div>
+</template>
+```
+
+These cause the error: `v-slot can only be used on components or <template> tags`
+
+**Correct:**
+```vue
+<template>
+  <!-- GOOD: v-slot on component element (default scoped slot) -->
+  <MyComponent v-slot="{ item }">
+    {{ item.name }}
+  </MyComponent>
+
+  <!-- GOOD: Named slots use template tags -->
+  <BaseLayout>
+    <template #header>
+      <h1>Title</h1>
+    </template>
+
+    <template #default>
+      <p>Main content</p>
+    </template>
+
+    <template #footer>
+      <p>Footer content</p>
+    </template>
+  </BaseLayout>
+
+  <!-- GOOD: Shorthand on component for default slot -->
+  <FancyList #default="{ item }">
+    <div>{{ item.name }}</div>
+  </FancyList>
+</template>
+```
+
+## Common Scenarios
+
+### Wrapping Slot Content in HTML
+If you need HTML wrappers around slot content, put them inside the template:
+
+```vue
+<!-- WRONG -->
+<MyComponent>
+  <div v-slot:header class="header-wrapper">
+    <h1>Title</h1>
+  </div>
+</MyComponent>
+
+<!-- CORRECT -->
+<MyComponent>
+  <template #header>
+    <div class="header-wrapper">
+      <h1>Title</h1>
+    </div>
+  </template>
+</MyComponent>
+```
+
+### Multiple v-slot on Same Element
+Another error occurs when you have multiple v-slot directives - only the first is recognized:
+
+```vue
+<!-- BAD: Multiple v-slot directives -->
+<MyComponent v-slot:header v-slot:footer>
+  Content
+</MyComponent>
+
+<!-- GOOD: Separate template for each slot -->
+<MyComponent>
+  <template #header>Header</template>
+  <template #footer>Footer</template>
+</MyComponent>
+```
+
+## Valid v-slot Locations
+
+| Element Type | v-slot Allowed? | Example |
+|--------------|-----------------|---------|
+| Component | Yes | `<MyComponent v-slot="props">` |
+| `<template>` | Yes | `<template #header>` |
+| `<div>` | No | Compilation error |
+| `<span>` | No | Compilation error |
+| Any HTML element | No | Compilation error |
+
+## Reference
+- [Vue.js Slots](https://vuejs.org/guide/components/slots.html)
+- [DeepScan - vue-misused-v-slot](https://deepscan.io/docs/rules/vue-misused-v-slot)

package/skills/vue-debug-guides/reference/ssr-hydration-mismatch-causes.md

@@ -0,0 +1,280 @@
+---
+title: Understand and Fix SSR Hydration Mismatches
+impact: HIGH
+impactDescription: Hydration mismatches cause visual flickering, performance loss, and broken functionality
+type: gotcha
+tags: [vue3, ssr, hydration, debugging, nuxt, server-side-rendering]
+---
+
+# Understand and Fix SSR Hydration Mismatches
+
+**Impact: HIGH** - Hydration mismatches occur when the HTML rendered on the client differs from what the server rendered. Vue attempts to recover by discarding and re-rendering mismatched nodes, causing performance degradation, visual flickering, and potentially broken event handlers.
+
+Understanding the common causes helps you prevent and debug these issues effectively.
+
+## Task Checklist
+
+- [ ] Validate HTML structure for proper nesting (no div in p, no nested a tags)
+- [ ] Move random value generation to onMounted or use seeded randoms
+- [ ] Format dates/times on client side only
+- [ ] Use `data-allow-mismatch` (Vue 3.5+) for intentional mismatches
+- [ ] Check for browser-modified HTML in dev tools
+
+## Cause 1: Invalid HTML Nesting
+
+Browsers auto-correct invalid HTML, creating different DOM than Vue expects.
+
+**Incorrect:**
+```vue
+<template>
+  <!-- WRONG: <div> cannot be inside <p> -->
+  <p>
+    <div>This will break hydration</div>
+  </p>
+
+  <!-- WRONG: <a> cannot be inside <a> -->
+  <a href="/parent">
+    <a href="/child">Nested link</a>
+  </a>
+
+  <!-- WRONG: Block elements in inline elements -->
+  <span>
+    <div>Block in inline</div>
+  </span>
+</template>
+```
+
+Browser converts the first example to:
+```html
+<p></p>
+<div>This will break hydration</div>
+<p></p>
+```
+
+**Correct:**
+```vue
+<template>
+  <!-- CORRECT: Use appropriate nesting -->
+  <div>
+    <div>This works fine</div>
+  </div>
+
+  <!-- CORRECT: Single link with event handling -->
+  <a href="/parent" @click="handleParentClick">
+    <span @click.stop="handleChildClick">Nested action</span>
+  </a>
+
+  <!-- CORRECT: Block element wrapper -->
+  <div>
+    <div>Block in block</div>
+  </div>
+</template>
+```
+
+## Cause 2: Random Values in Render
+
+Server and client generate different random values.
+
+**Incorrect:**
+```vue
+<template>
+  <!-- WRONG: Different ID on server vs client -->
+  <div :id="'field-' + Math.random()">
+    Form field
+  </div>
+
+  <!-- WRONG: Random order differs -->
+  <div v-for="item in shuffledItems" :key="item.id">
+    {{ item.name }}
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+
+const items = [/* ... */]
+
+// WRONG: Random shuffle runs differently on server and client
+const shuffledItems = computed(() =>
+  [...items].sort(() => Math.random() - 0.5)
+)
+</script>
+```
+
+**Correct - Client-Only Random:**
+```vue
+<template>
+  <div :id="fieldId">
+    Form field
+  </div>
+
+  <div v-for="item in displayItems" :key="item.id">
+    {{ item.name }}
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const items = [/* ... */]
+
+// CORRECT: Start with deterministic value
+const fieldId = ref('field-default')
+const displayItems = ref(items) // Original order on server
+
+onMounted(() => {
+  // Randomize only on client
+  fieldId.value = 'field-' + Math.random().toString(36).slice(2)
+  displayItems.value = [...items].sort(() => Math.random() - 0.5)
+})
+</script>
+```
+
+**Correct - Seeded Random:**
+```javascript
+// utils/seededRandom.js
+export function createSeededRandom(seed) {
+  return function() {
+    seed = (seed * 9301 + 49297) % 233280
+    return seed / 233280
+  }
+}
+
+// Use same seed on server and client
+const seed = 12345 // Could be based on user ID, page, etc.
+const random = createSeededRandom(seed)
+```
+
+## Cause 3: Timezone and Date Differences
+
+Server may be in different timezone than client.
+
+**Incorrect:**
+```vue
+<template>
+  <!-- WRONG: Server time != client time -->
+  <span>{{ new Date().toLocaleTimeString() }}</span>
+
+  <!-- WRONG: Server formats dates in server's timezone -->
+  <span>{{ formatDate(article.createdAt) }}</span>
+</template>
+
+<script setup>
+function formatDate(date) {
+  return new Date(date).toLocaleDateString()
+}
+</script>
+```
+
+**Correct:**
+```vue
+<template>
+  <!-- CORRECT: Render placeholder, update on client -->
+  <span>{{ displayTime || 'Loading...' }}</span>
+
+  <!-- CORRECT: Use UTC or defer to client -->
+  <span>{{ formattedDate }}</span>
+</template>
+
+<script setup>
+import { ref, computed, onMounted } from 'vue'
+
+const props = defineProps(['article'])
+const displayTime = ref(null)
+const isClient = ref(false)
+
+onMounted(() => {
+  displayTime.value = new Date().toLocaleTimeString()
+  isClient.value = true
+})
+
+// CORRECT: Server renders UTC, client converts to local
+const formattedDate = computed(() => {
+  if (!props.article?.createdAt) return ''
+
+  if (isClient.value) {
+    // Client: user's local timezone
+    return new Date(props.article.createdAt).toLocaleDateString()
+  } else {
+    // Server: consistent UTC format
+    return new Date(props.article.createdAt).toISOString().split('T')[0]
+  }
+})
+</script>
+```
+
+## Cause 4: Browser Extensions and Modifications
+
+Browser extensions can inject content into the DOM.
+
+**Mitigation:**
+```vue
+<template>
+  <!-- Use data-allow-mismatch for areas extensions might modify -->
+  <head data-allow-mismatch>
+    <title>{{ pageTitle }}</title>
+  </head>
+</template>
+```
+
+## Vue 3.5+ Suppressing Intentional Mismatches
+
+```vue
+<template>
+  <!-- Suppress specific mismatch types -->
+  <div data-allow-mismatch="text">
+    {{ clientOnlyText }}
+  </div>
+
+  <!-- Suppress all mismatches for this element -->
+  <div data-allow-mismatch>
+    <ComplexClientComponent />
+  </div>
+</template>
+```
+
+Valid `data-allow-mismatch` values:
+- `text` - Text content mismatches
+- `children` - Child element mismatches
+- `class` - Class attribute mismatches
+- `style` - Style attribute mismatches
+- `attribute` - Other attribute mismatches
+- (no value) - All mismatches
+
+## Debugging Hydration Mismatches
+
+```javascript
+// Enable detailed hydration mismatch warnings in development
+// vite.config.js
+export default {
+  define: {
+    __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: true
+  }
+}
+```
+
+```vue
+<script setup>
+import { onMounted } from 'vue'
+
+// Debug: Compare server HTML with client expectation
+onMounted(() => {
+  const serverHTML = document.getElementById('app').innerHTML
+  console.log('Server rendered:', serverHTML)
+})
+</script>
+```
+
+## Common Error Messages
+
+| Error | Likely Cause |
+|-------|--------------|
+| "Hydration text content mismatch" | Different text on server/client (dates, random) |
+| "Hydration children mismatch" | Invalid HTML nesting, conditional rendering |
+| "Hydration attribute mismatch" | Dynamic attributes with different values |
+| "Hydration node mismatch" | Completely different elements rendered |
+
+## Reference
+- [Vue.js SSR Guide - Hydration Mismatch](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch)
+- [Nuxt Hydration Best Practices](https://nuxt.com/docs/guide/best-practices/hydration)
+- [data-allow-mismatch RFC](https://github.com/vuejs/core/pull/9562)

package/skills/vue-debug-guides/reference/ssr-platform-specific-apis.md

@@ -0,0 +1,256 @@
+---
+title: Guard Platform-Specific APIs in Universal SSR Code
+impact: HIGH
+impactDescription: Accessing browser-only APIs on server causes crashes; Node.js APIs fail in browser
+type: gotcha
+tags: [vue3, ssr, browser-api, nodejs, universal, isomorphic, server-side-rendering]
+---
+
+# Guard Platform-Specific APIs in Universal SSR Code
+
+**Impact: HIGH** - SSR applications run the same code on both server (Node.js) and client (browser). Browser APIs like `window`, `document`, and `localStorage` don't exist in Node.js and will throw `ReferenceError`. Similarly, Node.js APIs like `fs` and `process` aren't available in browsers.
+
+Universal/isomorphic code must guard platform-specific API access or use libraries that work on both platforms.
+
+## Task Checklist
+
+- [ ] Never access `window`, `document`, `navigator` in `setup()` or `created()`
+- [ ] Move browser API access to `onMounted()` lifecycle hook
+- [ ] Use `typeof window !== 'undefined'` guard when needed outside lifecycle
+- [ ] Use cross-platform libraries for common functionality (fetch, storage)
+- [ ] Use Nuxt's `process.client` / `process.server` guards in Nuxt projects
+
+## Common Browser APIs That Break SSR
+
+| API | Node.js Behavior |
+|-----|-----------------|
+| `window` | `ReferenceError: window is not defined` |
+| `document` | `ReferenceError: document is not defined` |
+| `localStorage` / `sessionStorage` | `ReferenceError` |
+| `navigator` | `ReferenceError` |
+| `location` | `ReferenceError` |
+| `history` | `ReferenceError` |
+| `alert` / `confirm` / `prompt` | `ReferenceError` |
+| `requestAnimationFrame` | `ReferenceError` |
+| `IntersectionObserver` | `ReferenceError` |
+| `ResizeObserver` | `ReferenceError` |
+
+**Incorrect - Crashes on Server:**
+```javascript
+// WRONG: These run during setup/SSR - crashes in Node.js
+const width = ref(window.innerWidth)
+const theme = localStorage.getItem('theme')
+const userAgent = navigator.userAgent
+```
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+// WRONG: Runs on server, crashes
+const scrollY = ref(window.scrollY)
+
+// WRONG: document doesn't exist on server
+document.title = 'My Page'
+</script>
+```
+
+**Correct - Use onMounted:**
+```vue
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue'
+
+// Safe defaults that work on server
+const width = ref(0)
+const theme = ref('light')
+const scrollY = ref(0)
+
+onMounted(() => {
+  // Browser APIs only accessed after mount (client-only)
+  width.value = window.innerWidth
+  theme.value = localStorage.getItem('theme') || 'light'
+  scrollY.value = window.scrollY
+
+  // Event listeners safe in mounted
+  window.addEventListener('resize', handleResize)
+  window.addEventListener('scroll', handleScroll)
+})
+
+onUnmounted(() => {
+  window.removeEventListener('resize', handleResize)
+  window.removeEventListener('scroll', handleScroll)
+})
+
+function handleResize() {
+  width.value = window.innerWidth
+}
+
+function handleScroll() {
+  scrollY.value = window.scrollY
+}
+</script>
+```
+
+**Correct - Guard with typeof:**
+```javascript
+// When you need to check outside lifecycle hooks
+function getStoredValue(key, defaultValue) {
+  if (typeof window !== 'undefined' && window.localStorage) {
+    return localStorage.getItem(key) ?? defaultValue
+  }
+  return defaultValue
+}
+
+// Composable with SSR awareness
+export function useMediaQuery(query) {
+  const matches = ref(false)
+
+  // Only run on client
+  if (typeof window !== 'undefined') {
+    const mediaQuery = window.matchMedia(query)
+    matches.value = mediaQuery.matches
+
+    // Setup listener in lifecycle
+    onMounted(() => {
+      const handler = (e) => { matches.value = e.matches }
+      mediaQuery.addEventListener('change', handler)
+      onUnmounted(() => mediaQuery.removeEventListener('change', handler))
+    })
+  }
+
+  return matches
+}
+```
+
+## Nuxt.js Guards
+
+```vue
+<script setup>
+// Nuxt provides process.client and process.server
+if (process.client) {
+  // Only runs in browser
+  window.analytics.track('page_view')
+}
+
+if (process.server) {
+  // Only runs on server
+  console.log('Rendering on server')
+}
+</script>
+```
+
+```vue
+<template>
+  <!-- ClientOnly component for client-only rendering -->
+  <ClientOnly>
+    <BrowserOnlyChart :data="chartData" />
+    <template #fallback>
+      <ChartSkeleton />
+    </template>
+  </ClientOnly>
+</template>
+```
+
+## Cross-Platform Libraries
+
+Use libraries that abstract platform differences:
+
+```javascript
+// Fetch - works in both Node.js 18+ and browsers
+const response = await fetch('/api/data')
+
+// For older Node.js, use node-fetch or axios
+import axios from 'axios'
+const { data } = await axios.get('/api/data')
+```
+
+```javascript
+// Universal cookie handling
+import Cookies from 'js-cookie' // Client only
+import { parse } from 'cookie' // Works both
+
+// In Nuxt, use useCookie()
+const token = useCookie('auth-token')
+```
+
+## Common Node.js APIs That Break in Browser
+
+| API | Browser Behavior |
+|-----|-----------------|
+| `fs` | Module not found |
+| `path` | Module not found |
+| `process` (full) | Undefined or limited |
+| `Buffer` | Undefined (unless polyfilled) |
+| `__dirname` / `__filename` | Undefined |
+| `require()` | Undefined in ES modules |
+
+**Incorrect:**
+```javascript
+// WRONG: Node.js APIs in universal code
+import fs from 'fs'
+const config = JSON.parse(fs.readFileSync('./config.json'))
+```
+
+**Correct - Separate Server Code:**
+```javascript
+// server/utils.js - Server-only file
+import fs from 'fs'
+export function loadConfig() {
+  return JSON.parse(fs.readFileSync('./config.json'))
+}
+
+// app.js - Universal code uses API instead
+const config = await fetch('/api/config').then(r => r.json())
+```
+
+## Environment Detection Utility
+
+```javascript
+// utils/environment.js
+export const isClient = typeof window !== 'undefined'
+export const isServer = !isClient
+
+export const isBrowser = isClient && typeof document !== 'undefined'
+export const isNode = typeof process !== 'undefined' &&
+                      process.versions?.node != null
+
+// Usage
+import { isClient, isServer } from '@/utils/environment'
+
+if (isClient) {
+  // Browser-specific code
+}
+```
+
+## Third-Party Library Issues
+
+Some libraries auto-access browser APIs on import:
+
+```javascript
+// WRONG: Library accesses window on import
+import SomeChartLibrary from 'some-chart-library'
+// ^ Crashes on server if library does: const x = window.something
+```
+
+**Correct - Dynamic Import:**
+```vue
+<script setup>
+import { defineAsyncComponent } from 'vue'
+
+// Dynamic import only loads on client
+const Chart = defineAsyncComponent(() =>
+  import('some-chart-library').then(m => m.ChartComponent)
+)
+</script>
+
+<template>
+  <ClientOnly>
+    <Chart :data="data" />
+  </ClientOnly>
+</template>
+```
+
+## Reference
+- [Vue.js SSR - Platform-Specific APIs](https://vuejs.org/guide/scaling-up/ssr.html#access-to-platform-specific-apis)
+- [Nuxt ClientOnly Component](https://nuxt.com/docs/api/components/client-only)
+- [MDN: Web APIs](https://developer.mozilla.org/en-US/docs/Web/API)