@pythoughts/vue-skills-mcp 0.1.0

package/skills/vue-debug-guides/reference/state-ssr-cross-request-pollution.md

@@ -0,0 +1,276 @@
+---
+title: Prevent Cross-Request State Pollution in SSR Applications
+impact: CRITICAL
+impactDescription: Singleton stores in SSR share state across all server requests, potentially leaking user data between requests
+type: gotcha
+tags: [vue3, ssr, state-management, pinia, vuex, security, server-side-rendering, nuxt]
+---
+
+# Prevent Cross-Request State Pollution in SSR Applications
+
+**Impact: CRITICAL** - In Server-Side Rendering (SSR) applications, a singleton store pattern creates a single instance that is shared across all server requests. This means data from one user's request could leak into another user's response, causing serious security and data integrity issues.
+
+This is one of the most critical gotchas in Vue state management that can have severe production consequences.
+
+## Task Checklist
+
+- [ ] Never use a singleton store pattern in SSR applications
+- [ ] Create a fresh store instance per request when using SSR
+- [ ] Use Pinia which handles SSR state management correctly
+- [ ] Test SSR state isolation with concurrent requests
+- [ ] Review any global reactive state for SSR compatibility
+
+## The Problem: Singleton State in SSR
+
+```javascript
+// store.js - DANGEROUS for SSR
+import { reactive } from 'vue'
+
+// This is a singleton - same instance for ALL requests
+export const store = reactive({
+  user: null,
+  cart: [],
+  preferences: {}
+})
+```
+
+**What happens in SSR:**
+
+1. Request A comes in for User A
+2. Server sets `store.user = userA`
+3. Before response completes, Request B arrives for User B
+4. Request B sees `store.user = userA` (User A's data leaked!)
+5. Server sets `store.user = userB`
+6. Request A's response might now contain User B's data
+
+This creates unpredictable behavior and potential security vulnerabilities.
+
+## Solution 1: Use Pinia (Recommended)
+
+Pinia handles SSR correctly by creating fresh store instances per request:
+
+```javascript
+// stores/user.js
+import { defineStore } from 'pinia'
+
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    user: null,
+    preferences: {}
+  }),
+  actions: {
+    setUser(user) {
+      this.user = user
+    }
+  }
+})
+```
+
+```javascript
+// main.js (or entry-server.js)
+import { createPinia } from 'pinia'
+import { createApp } from 'vue'
+import App from './App.vue'
+
+// For SSR: Create fresh instances per request
+export function createAppInstance() {
+  const app = createApp(App)
+  const pinia = createPinia()
+
+  app.use(pinia)
+
+  return { app, pinia }
+}
+```
+
+```javascript
+// entry-server.js
+import { createAppInstance } from './main'
+import { renderToString } from 'vue/server-renderer'
+
+export async function render(url, context) {
+  // Fresh app and store instance per request
+  const { app, pinia } = createAppInstance()
+
+  // ... setup router, fetch data, etc.
+
+  const html = await renderToString(app)
+
+  // Serialize state for client hydration
+  const state = pinia.state.value
+
+  return { html, state }
+}
+```
+
+```javascript
+// entry-client.js - Hydrate from serialized state
+import { createAppInstance } from './main'
+
+const { app, pinia } = createAppInstance()
+
+// Restore server state before mounting
+if (window.__PINIA_STATE__) {
+  pinia.state.value = window.__PINIA_STATE__
+}
+
+app.mount('#app')
+```
+
+## Solution 2: Factory Pattern for Hand-Rolled State
+
+If not using Pinia, create a factory function:
+
+```javascript
+// store.js - SSR-safe with factory
+import { reactive, readonly } from 'vue'
+
+// Factory function creates fresh state per call
+export function createStore() {
+  const state = reactive({
+    user: null,
+    cart: [],
+    preferences: {}
+  })
+
+  return {
+    state: readonly(state),
+    setUser(user) {
+      state.user = user
+    },
+    addToCart(item) {
+      state.cart.push(item)
+    }
+  }
+}
+```
+
+```javascript
+// entry-server.js
+import { createStore } from './store'
+import { provide } from 'vue'
+
+export async function render(url) {
+  const app = createApp(App)
+
+  // Fresh store instance for this request only
+  const store = createStore()
+  app.provide('store', store)
+
+  // ... render
+}
+```
+
+## Solution 3: Context-Based State (Advanced)
+
+For frameworks like Nuxt, use request context:
+
+```javascript
+// composables/useRequestState.js
+import { useSSRContext } from 'vue'
+
+export function useRequestState(key, initialValue) {
+  if (import.meta.env.SSR) {
+    const ctx = useSSRContext()
+    ctx.state = ctx.state || {}
+
+    if (!(key in ctx.state)) {
+      ctx.state[key] = initialValue()
+    }
+
+    return ctx.state[key]
+  }
+
+  // Client-side: use regular reactive state
+  return reactive(initialValue())
+}
+```
+
+## Nuxt.js Handles This Automatically
+
+In Nuxt 3, state isolation is handled automatically:
+
+```javascript
+// Nuxt automatically creates fresh Pinia instance per request
+// You can use stores normally
+
+export default defineNuxtPlugin(async (nuxtApp) => {
+  const userStore = useUserStore()
+  await userStore.fetchUser()
+})
+```
+
+## Testing for State Pollution
+
+```javascript
+// test/ssr-state-isolation.test.js
+import { describe, it, expect } from 'vitest'
+import { render } from './entry-server'
+
+describe('SSR State Isolation', () => {
+  it('should not leak state between concurrent requests', async () => {
+    // Simulate concurrent requests
+    const [result1, result2] = await Promise.all([
+      render('/user/1', { userId: '1' }),
+      render('/user/2', { userId: '2' })
+    ])
+
+    // Each should have their own user data
+    expect(result1.html).toContain('User 1')
+    expect(result2.html).toContain('User 2')
+
+    // State should not be mixed
+    expect(result1.html).not.toContain('User 2')
+    expect(result2.html).not.toContain('User 1')
+  })
+})
+```
+
+```javascript
+// Alternative: Test store isolation directly
+import { createApp } from './app.js'
+
+test('requests do not share state', async () => {
+  // Simulate two concurrent requests
+  const { app: app1, store: store1 } = createApp()
+  const { app: app2, store: store2 } = createApp()
+
+  store1.user = { id: 1, name: 'Alice' }
+  store2.user = { id: 2, name: 'Bob' }
+
+  // Each should have its own state
+  expect(store1.user.name).toBe('Alice')
+  expect(store2.user.name).toBe('Bob')
+})
+```
+
+## Red Flags to Watch For
+
+```javascript
+// ANY module-level reactive state is dangerous in SSR
+
+// BAD: Module-level reactive
+export const globalUser = ref(null)
+
+// BAD: Module-level reactive object
+export const appState = reactive({})
+
+// BAD: Shared Map/Set
+export const cache = new Map()
+
+// BAD: Even plain objects can be problematic
+let requestCount = 0  // Shared across requests
+```
+
+## Why Pinia is Recommended for SSR
+
+1. **Automatic request isolation** - Fresh store instances per request
+2. **Built-in state serialization** - Easy hydration on client
+3. **DevTools support** - Debug state on both server and client
+4. **TypeScript support** - Type-safe state management
+5. **Tested patterns** - Battle-tested SSR handling
+
+## Reference
+- [Vue.js State Management - SSR Considerations](https://vuejs.org/guide/scaling-up/state-management.html#ssr-considerations)
+- [Pinia SSR Guide](https://pinia.vuejs.org/ssr/)
+- [Vue SSR Guide](https://vuejs.org/guide/scaling-up/ssr.html)

package/skills/vue-debug-guides/reference/suspense-no-builtin-error-handling.md

@@ -0,0 +1,127 @@
+# Suspense Has No Built-in Error Handling
+
+## Rule
+
+`<Suspense>` does not provide error handling via the component itself. You must implement error handling using `errorCaptured` option or `onErrorCaptured()` hook in a parent component to catch async errors.
+
+## Why This Matters
+
+Without explicit error handling, async errors in suspended components will propagate uncaught, potentially crashing the application or leaving users stuck on loading states. Unlike React's Error Boundaries, Vue's Suspense requires manual error boundary implementation.
+
+## Bad Code
+
+```vue
+<script setup>
+// No error handling - async errors will propagate uncaught
+</script>
+
+<template>
+  <Suspense>
+    <AsyncComponent />
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+## Good Code
+
+```vue
+<script setup>
+import { ref, onErrorCaptured } from 'vue'
+import AsyncComponent from './AsyncComponent.vue'
+
+const error = ref(null)
+
+onErrorCaptured((err) => {
+  error.value = err
+  return false // Prevent error from propagating further
+})
+</script>
+
+<template>
+  <div v-if="error" class="error-state">
+    <p>Something went wrong: {{ error.message }}</p>
+    <button @click="error = null">Retry</button>
+  </div>
+
+  <Suspense v-else>
+    <AsyncComponent />
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+```
+
+## Reusable Error Boundary Pattern
+
+```vue
+<!-- ErrorBoundary.vue -->
+<script setup>
+import { ref, onErrorCaptured } from 'vue'
+
+const props = defineProps({
+  fallback: {
+    type: String,
+    default: 'Something went wrong'
+  }
+})
+
+const emit = defineEmits(['error'])
+
+const error = ref(null)
+
+onErrorCaptured((err, instance, info) => {
+  error.value = { err, instance, info }
+  emit('error', { err, instance, info })
+  return false
+})
+
+const reset = () => {
+  error.value = null
+}
+
+defineExpose({ reset })
+</script>
+
+<template>
+  <slot v-if="!error" />
+  <slot v-else name="error" :error="error" :reset="reset">
+    <div class="error-boundary">
+      {{ fallback }}
+      <button @click="reset">Retry</button>
+    </div>
+  </slot>
+</template>
+```
+
+```vue
+<!-- Usage -->
+<template>
+  <ErrorBoundary @error="logError">
+    <Suspense>
+      <AsyncDashboard />
+      <template #fallback>Loading dashboard...</template>
+    </Suspense>
+
+    <template #error="{ error, reset }">
+      <DashboardError :error="error" @retry="reset" />
+    </template>
+  </ErrorBoundary>
+</template>
+```
+
+## Key Points
+
+1. Always wrap `<Suspense>` with error handling logic in production
+2. Use `onErrorCaptured` for Composition API or `errorCaptured` option for Options API
+3. Return `false` from the error handler to stop propagation
+4. Consider creating a reusable `ErrorBoundary` component to reduce boilerplate
+5. Provide a way for users to retry failed operations
+
+## References
+
+- [Vue.js Suspense Documentation](https://vuejs.org/guide/built-ins/suspense#error-handling)
+- [Vue.js onErrorCaptured](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured)

package/skills/vue-debug-guides/reference/suspense-ssr-hydration-issues.md

@@ -0,0 +1,159 @@
+# Suspense SSR Hydration Issues and Workarounds
+
+## Rule
+
+`<Suspense>` has known issues with SSR hydration, particularly with async components. During initial hydration, Suspense may not properly include child components within its "cloak of suspense," leading to hydration mismatches, flickering, or runtime crashes.
+
+## Why This Matters
+
+In SSR applications, hydration mismatches cause:
+- Visual flickering as the client re-renders
+- Loss of state in affected components
+- Console warnings in development (silent failures in production)
+- Potential runtime crashes in edge cases
+- Poor user experience, especially on slower networks
+
+## Bad Code
+
+```vue
+<template>
+  <!-- Async component directly in Suspense can fail hydration -->
+  <Suspense>
+    <AsyncDashboard />
+    <template #fallback>
+      Loading...
+    </template>
+  </Suspense>
+</template>
+
+<script setup>
+import { defineAsyncComponent } from 'vue'
+
+const AsyncDashboard = defineAsyncComponent(
+  () => import('./Dashboard.vue')
+)
+</script>
+```
+
+## Good Code
+
+### Solution 1: Wrap Async Components with Suspense
+
+```vue
+<template>
+  <!-- Each async component wrapped in its own Suspense -->
+  <div class="dashboard">
+    <Suspense>
+      <AsyncHeader />
+      <template #fallback><HeaderSkeleton /></template>
+    </Suspense>
+
+    <Suspense>
+      <AsyncContent />
+      <template #fallback><ContentSkeleton /></template>
+    </Suspense>
+  </div>
+</template>
+```
+
+### Solution 2: Use ClientOnly Wrapper (Nuxt/SSR Frameworks)
+
+```vue
+<template>
+  <!-- Prevent SSR for problematic async components -->
+  <ClientOnly>
+    <Suspense>
+      <AsyncDashboard />
+      <template #fallback>
+        Loading dashboard...
+      </template>
+    </Suspense>
+
+    <template #fallback>
+      <DashboardSkeleton />
+    </template>
+  </ClientOnly>
+</template>
+```
+
+### Solution 3: Prefetch with Proper Stale Time (with TanStack Query)
+
+```vue
+<script setup>
+import { useQuery, useQueryClient } from '@tanstack/vue-query'
+
+// IMPORTANT: All useQuery calls must be BEFORE any await
+const { data, suspense } = useQuery({
+  queryKey: ['dashboard'],
+  queryFn: fetchDashboardData,
+  staleTime: 1000 * 60 * 5, // 5 minutes - prevents refetch after hydration
+})
+
+// Wait for suspense AFTER all useQuery calls
+await suspense()
+
+// Now safe to use data
+</script>
+```
+
+### Solution 4: Handle Hydration Errors Gracefully
+
+```vue
+<script setup>
+import { ref, onErrorCaptured, onMounted } from 'vue'
+
+const hydrationError = ref(false)
+const isClient = ref(false)
+
+onMounted(() => {
+  isClient.value = true
+})
+
+onErrorCaptured((err) => {
+  if (err.message?.includes('hydration')) {
+    hydrationError.value = true
+    return false
+  }
+})
+</script>
+
+<template>
+  <div v-if="hydrationError" class="hydration-recovery">
+    <!-- Force client-only re-render -->
+    <Suspense v-if="isClient">
+      <AsyncContent />
+      <template #fallback>Recovering...</template>
+    </Suspense>
+  </div>
+
+  <Suspense v-else>
+    <AsyncContent />
+    <template #fallback>Loading...</template>
+  </Suspense>
+</template>
+```
+
+## Common SSR + Suspense Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Hydration mismatch | Async chunk not loaded in time | Wrap with Suspense or use ClientOnly |
+| Empty flash on Safari | Slow chunk loading | Preload critical chunks, use skeleton |
+| useQuery after await error | Vue context lost after await | Put all useQuery calls before any await |
+| Immediate refetch after hydration | staleTime too low | Set appropriate staleTime value |
+
+## Key Points
+
+1. Suspense + SSR has known edge cases - test thoroughly
+2. Safari has slower chunk loading that triggers more hydration issues
+3. With data-fetching libraries, ensure queries are set up before awaiting suspense
+4. Consider ClientOnly wrappers for non-critical async content
+5. Set appropriate staleTime to prevent unnecessary refetches after hydration
+6. Use skeleton screens that match server-rendered content structure
+
+## References
+
+- [Vue.js Suspense Documentation](https://vuejs.org/guide/built-ins/suspense)
+- [Vue Issue #6638 - Suspense hydration](https://github.com/vuejs/core/issues/6638)
+- [Vue Issue #7672 - defineAsyncComponent SSR](https://github.com/vuejs/core/issues/7672)
+- [TanStack Query SSR Discussion](https://github.com/TanStack/query/discussions/4870)

package/skills/vue-debug-guides/reference/tailwind-dynamic-class-generation.md

@@ -0,0 +1,144 @@
+# Tailwind CSS Dynamic Class Generation
+
+## Rule
+
+Never construct Tailwind CSS class names dynamically using string concatenation or template literals. Tailwind's build process cannot detect dynamically generated class names, causing styles to be missing in production.
+
+## Why This Matters
+
+- Tailwind uses static analysis at build time to determine which CSS classes to include
+- Dynamically constructed class names (e.g., `bg-${color}-500`) are invisible to Tailwind's scanner
+- Classes work in development with JIT but fail silently in production builds
+- This is a common source of "it works locally but not in production" bugs
+
+## Bad Code
+
+```vue
+<script setup>
+const props = defineProps({
+  color: String, // 'red', 'blue', 'green'
+  size: String   // 'sm', 'md', 'lg'
+})
+</script>
+
+<template>
+  <!-- WRONG: Tailwind cannot detect these classes -->
+  <div :class="`bg-${color}-500 text-${size}`">
+    Content
+  </div>
+
+  <!-- WRONG: String concatenation -->
+  <div :class="'p-' + padding">
+    Content
+  </div>
+
+  <!-- WRONG: Template literal in array -->
+  <div :class="[`gap-x-${spacing}`]">
+    Content
+  </div>
+</template>
+```
+
+## Good Code
+
+```vue
+<script setup>
+const props = defineProps({
+  color: String,
+  size: String
+})
+
+// Use a mapping object with complete class names
+const colorClasses = {
+  red: 'bg-red-500',
+  blue: 'bg-blue-500',
+  green: 'bg-green-500'
+}
+
+const sizeClasses = {
+  sm: 'text-sm p-2',
+  md: 'text-base p-4',
+  lg: 'text-lg p-6'
+}
+</script>
+
+<template>
+  <!-- CORRECT: Full class names that Tailwind can detect -->
+  <div :class="[colorClasses[color], sizeClasses[size]]">
+    Content
+  </div>
+</template>
+```
+
+## Using Conditional Objects
+
+```vue
+<script setup>
+const props = defineProps({
+  variant: String // 'primary', 'secondary', 'danger'
+})
+</script>
+
+<template>
+  <!-- CORRECT: All class names are complete strings -->
+  <button :class="{
+    'bg-blue-500 hover:bg-blue-600': variant === 'primary',
+    'bg-gray-500 hover:bg-gray-600': variant === 'secondary',
+    'bg-red-500 hover:bg-red-600': variant === 'danger'
+  }">
+    Click me
+  </button>
+</template>
+```
+
+## Safelist for Truly Dynamic Classes
+
+If you must use dynamic classes, add them to Tailwind's safelist:
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  safelist: [
+    'bg-red-500',
+    'bg-blue-500',
+    'bg-green-500',
+    // Or use patterns (use sparingly - increases bundle size)
+    {
+      pattern: /bg-(red|blue|green)-(100|500|900)/
+    }
+  ]
+}
+```
+
+## Alternative: CSS Custom Properties
+
+For truly dynamic values, use CSS custom properties:
+
+```vue
+<script setup>
+const props = defineProps({
+  customColor: String // Any hex color
+})
+</script>
+
+<template>
+  <!-- Use CSS variable for truly dynamic values -->
+  <div
+    class="dynamic-bg"
+    :style="{ '--dynamic-color': customColor }"
+  >
+    Content
+  </div>
+</template>
+
+<style>
+.dynamic-bg {
+  background-color: var(--dynamic-color);
+}
+</style>
+```
+
+## References
+
+- [Tailwind CSS Dynamic Class Names](https://tailwindcss.com/docs/content-configuration#dynamic-class-names)
+- [Tailwind Safelist](https://tailwindcss.com/docs/content-configuration#safelisting-classes)