@codihaus/claude-skills 1.6.18 → 1.6.20

package/knowledge/stacks/vue/_index.md

@@ -0,0 +1,750 @@
+# Vue 3
+
+> Progressive JavaScript framework for building user interfaces
+
+## Overview
+
+**What it is:**
+- Progressive framework (incrementally adoptable)
+- Component-based with Single File Components (SFCs)
+- Composition API for logic reuse (Vue 3+)
+- Reactive and declarative
+- Virtual DOM with optimized reactivity
+- Template syntax with directives
+
+**When to use:**
+- Building interactive user interfaces
+- Single-page applications (SPAs)
+- Progressive enhancement of existing sites
+- Projects needing gentle learning curve
+- Teams wanting flexibility and simplicity
+
+**Key concepts:**
+- **SFC (Single File Component)** = .vue files with template, script, style
+- **Composition API** = Composable logic with setup()
+- **Reactivity** = ref(), reactive(), computed(), watch()
+- **Template Syntax** = Directives (v-if, v-for, v-bind, v-on)
+- **Components** = Reusable building blocks
+- **Props & Emits** = Parent-child communication
+- **Provide/Inject** = Dependency injection
+
+## Best Practices
+
+### Project Structure
+
+```
+vue-app/
+├── src/
+│   ├── components/           # Reusable components
+│   │   ├── ui/               # UI primitives
+│   │   ├── forms/            # Form components
+│   │   └── common/           # Shared components
+│   ├── composables/          # Composition API composables
+│   │   └── useAuth.js        # use* naming convention
+│   ├── views/                # Page components (routes)
+│   ├── stores/               # Pinia stores
+│   ├── router/               # Vue Router config
+│   ├── assets/               # Static assets
+│   ├── utils/                # Helper functions
+│   ├── types/                # TypeScript types
+│   ├── App.vue               # Root component
+│   └── main.js               # Entry point
+└── public/                   # Public static files
+```
+
+### Component Structure (SFC)
+
+```vue
+<!-- ComponentName.vue -->
+<script setup>
+// 1. Imports
+import { ref, computed, watch, onMounted } from 'vue'
+import { useRouter } from 'vue-router'
+
+// 2. Props & Emits
+const props = defineProps({
+  title: String,
+  count: { type: Number, required: true }
+})
+
+const emit = defineEmits(['update', 'close'])
+
+// 3. Composables
+const router = useRouter()
+const { user } = useAuth()
+
+// 4. Reactive state
+const localCount = ref(0)
+const doubled = computed(() => localCount.value * 2)
+
+// 5. Methods
+function increment() {
+  localCount.value++
+  emit('update', localCount.value)
+}
+
+// 6. Watchers
+watch(() => props.count, (newVal) => {
+  localCount.value = newVal
+})
+
+// 7. Lifecycle hooks
+onMounted(() => {
+  console.log('Component mounted')
+})
+</script>
+
+<template>
+  <div class="component">
+    <h1>{{ title }}</h1>
+    <p>Count: {{ localCount }}</p>
+    <p>Doubled: {{ doubled }}</p>
+    <button @click="increment">Increment</button>
+  </div>
+</template>
+
+<style scoped>
+.component {
+  /* Component styles */
+}
+</style>
+```
+
+### Composition API Best Practices
+
+**Using `<script setup>` (Recommended):**
+```vue
+DO:
+✓ Use <script setup> (less boilerplate)
+✓ Name composables with "use" prefix
+✓ Keep composables focused (single concern)
+✓ Return reactive values from composables
+✓ Use ref() for primitives, reactive() for objects
+
+DON'T:
+✗ Mix Options API and Composition API
+✗ Use setup() function (use <script setup> instead)
+✗ Destructure reactive objects (loses reactivity)
+✗ Forget .value on refs in script
+✗ Over-abstract into composables too early
+```
+
+**Reactivity:**
+```javascript
+DO:
+✓ Use ref() for primitives
+const count = ref(0)
+count.value++ // Access with .value in script
+
+✓ Use reactive() for objects
+const state = reactive({ count: 0 })
+state.count++ // No .value needed
+
+✓ Use computed() for derived state
+const doubled = computed(() => count.value * 2)
+
+✓ Use toRefs() when destructuring reactive objects
+const { count } = toRefs(state)
+
+DON'T:
+✗ Reassign reactive() (loses reactivity)
+state = { count: 1 } // Wrong
+state.count = 1 // Correct
+
+✗ Destructure reactive() directly
+const { count } = reactive({ count: 0 }) // Loses reactivity
+
+✗ Use ref() for large objects (use reactive())
+✗ Compute values in watchers (use computed)
+```
+
+**Composables Pattern:**
+```javascript
+DO:
+✓ Export composable function starting with "use"
+✓ Return reactive values (refs, computed)
+✓ Keep composables composable (can call other composables)
+✓ Handle cleanup in onUnmounted
+
+DON'T:
+✗ Call composables conditionally
+✗ Call composables in callbacks
+✗ Call composables outside setup()
+✗ Return plain values (use ref/reactive)
+```
+
+### Template Best Practices
+
+**Directives:**
+```vue
+DO:
+✓ Use v-bind shorthand (:prop)
+<img :src="imageUrl">
+
+✓ Use v-on shorthand (@event)
+<button @click="handler">
+
+✓ Use v-for with unique :key
+<div v-for="item in items" :key="item.id">
+
+✓ Use v-if for conditional rendering
+<div v-if="show">Content</div>
+
+✓ Use v-show for frequent toggles
+<div v-show="visible">Content</div>
+
+DON'T:
+✗ Use v-for with v-if on same element (use computed filter)
+<div v-for="item in items" v-if="item.active"> <!-- BAD -->
+
+✗ Use index as key for dynamic lists
+v-for="(item, i) in items" :key="i" <!-- BAD -->
+
+✗ Forget :key in v-for
+✗ Use v-html with user input (XSS risk)
+```
+
+**Component Communication:**
+```vue
+DO:
+✓ Use props for parent → child
+<Child :title="parentTitle" />
+
+✓ Use emits for child → parent
+emit('update', value)
+
+✓ Use provide/inject for deep hierarchies
+provide('key', value)
+const value = inject('key')
+
+✓ Use Pinia for global state
+
+DON'T:
+✗ Mutate props directly (one-way data flow)
+props.title = 'new' // Wrong
+emit('update:title', 'new') // Correct
+
+✗ Prop drill through many levels (use provide/inject)
+✗ Use event bus (deprecated in Vue 3)
+✗ Access $parent or $root (tight coupling)
+```
+
+### State Management
+
+**Local State:**
+```javascript
+When: Component-specific, not shared
+Example: Form inputs, toggles, local UI state
+Use: ref(), reactive()
+```
+
+**Composables:**
+```javascript
+When: Reusable logic, shared between components
+Example: useAuth(), useFetch(), useForm()
+Use: Composable functions returning refs/computed
+```
+
+**Pinia (Global Store):**
+```javascript
+When: Global or feature-level state
+Example: Auth state, cart, user preferences
+DO:
+✓ One store per feature/domain
+✓ Use composition stores (setup syntax)
+✓ Keep actions for mutations
+✓ Use getters for computed state
+✓ Modularize stores
+
+DON'T:
+✗ Use Vuex (Pinia is official for Vue 3)
+✗ Create one giant store
+✗ Mutate state outside actions
+✗ Store derived data (use getters)
+```
+
+### Performance Optimization
+
+**Lazy Loading:**
+```javascript
+DO:
+✓ Lazy load routes
+const Home = () => import('./views/Home.vue')
+
+✓ Lazy load heavy components
+const Chart = defineAsyncComponent(() => import('./Chart.vue'))
+
+✓ Use Suspense for async components
+<Suspense>
+  <AsyncComponent />
+</Suspense>
+
+DON'T:
+✗ Lazy load small components (overhead)
+✗ Forget loading/error states
+```
+
+**Reactivity Optimization:**
+```javascript
+DO:
+✓ Use shallowRef() for large objects (no deep reactivity)
+✓ Use shallowReactive() for large structures
+✓ Mark constants with markRaw()
+✓ Use v-once for static content
+✓ Use v-memo for expensive list items
+
+DON'T:
+✗ Create reactivity for everything
+✗ Deep watch large objects unnecessarily
+✗ Forget to unwatch in cleanup
+```
+
+**List Rendering:**
+```vue
+DO:
+✓ Use unique, stable keys (IDs from data)
+<div v-for="item in items" :key="item.id">
+
+✓ Filter/sort in computed, not in template
+const filtered = computed(() => items.filter(fn))
+
+✓ Use v-memo for expensive items
+<div v-for="item in items" :key="item.id" v-memo="[item.id]">
+
+DON'T:
+✗ Use index as key for dynamic lists
+✗ Filter/sort directly in v-for
+✗ Create objects/arrays in template (re-renders)
+```
+
+### Forms & v-model
+
+```vue
+DO:
+✓ Use v-model for two-way binding
+<input v-model="text">
+
+✓ Use v-model modifiers
+<input v-model.trim="text">
+<input v-model.number="age">
+
+✓ Use custom v-model on components
+defineProps(['modelValue'])
+defineEmits(['update:modelValue'])
+
+✓ Validate on blur or submit
+
+DON'T:
+✗ Validate on every keystroke (performance)
+✗ Forget to trim/sanitize inputs
+✗ Store all form state in parent (use composables)
+```
+
+### TypeScript Integration
+
+```typescript
+DO:
+✓ Define prop types with TypeScript
+defineProps<{
+  title: string
+  count?: number
+}>()
+
+✓ Type emit functions
+const emit = defineEmits<{
+  update: [value: number]
+  close: []
+}>()
+
+✓ Type composables return values
+function useCounter(): { count: Ref<number>, increment: () => void }
+
+✓ Use generic components
+defineComponent<Props, Emits>()
+
+DON'T:
+✗ Use PropType with <script setup> (use TS interface)
+✗ Forget to type composables
+✗ Over-use any
+```
+
+## Anti-Patterns
+
+### Common Mistakes
+
+```vue
+❌ Mutating props
+props.value = 'new' // Wrong
+emit('update:value', 'new') // Correct
+
+❌ v-for without :key
+<div v-for="item in items"> <!-- Missing :key -->
+
+❌ v-for + v-if on same element
+<div v-for="item in items" v-if="item.active"> <!-- Use computed -->
+
+❌ Destructuring reactive without toRefs
+const { count } = reactive({ count: 0 }) // Loses reactivity
+const { count } = toRefs(reactive({ count: 0 })) // Correct
+
+❌ Not accessing .value on refs in script
+const count = ref(0)
+console.log(count) // Wrong: Ref object
+console.log(count.value) // Correct
+
+❌ Creating reactive values in template
+<Component :data="{ value: x }" /> <!-- New object every render -->
+
+❌ Large computed without caching
+// Computed should be pure and efficient
+const expensive = computed(() => {
+  // Heavy calculation on every access
+})
+
+❌ Conditional composables
+if (condition) {
+  const data = useData() // Wrong: must be at top level
+}
+```
+
+## For /dev-specs
+
+When writing specs for Vue 3 projects:
+
+**Component Specs:**
+- Define props (name, type, required, default)
+- Define emits (event names, payload types)
+- Specify state management approach (local, composable, Pinia)
+- Identify if lazy loading needed
+- Note if TypeScript types required
+
+**State Management:**
+- Clarify scope (local, composable, Pinia store)
+- If Pinia: specify store name and location
+- If composable: specify composable name and return shape
+
+**Performance Requirements:**
+- List optimization needs (lazy load, v-memo, shallow)
+- Specify bundle size constraints
+
+**Patterns to Use:**
+- Composables for reusable logic
+- Provide/inject for deep prop drilling
+- Pinia stores for global state
+
+## For /dev-coding
+
+When implementing Vue 3 features:
+
+### 1. Component Creation
+
+**Start with:**
+- Read tech-context.md for project's Vue patterns
+- Check if TypeScript is used
+- Identify state management approach (Pinia, composables)
+- Check for UI library (Vuetify, PrimeVue, Element Plus, etc.)
+
+**Structure:**
+```vue
+<script setup lang="ts">
+// 1. Imports
+import { ref, computed, watch, onMounted } from 'vue'
+
+// 2. Props & Emits
+const props = defineProps<{
+  title: string
+  count: number
+}>()
+
+const emit = defineEmits<{
+  update: [value: number]
+}>()
+
+// 3. Composables
+const { user, loading } = useAuth()
+
+// 4. State
+const localState = ref(0)
+const derived = computed(() => localState.value * 2)
+
+// 5. Methods
+function handleClick() {
+  emit('update', localState.value)
+}
+
+// 6. Watchers
+watch(() => props.count, (newVal) => {
+  localState.value = newVal
+})
+
+// 7. Lifecycle
+onMounted(() => {
+  // Setup logic
+})
+</script>
+
+<template>
+  <div>
+    <!-- Template -->
+  </div>
+</template>
+
+<style scoped>
+/* Scoped styles */
+</style>
+```
+
+### 2. State Management
+
+**Choose based on scope:**
+- **Local UI state** → ref(), reactive()
+- **Reusable logic** → Composable (useX)
+- **Feature-level** → Pinia store
+- **Deep hierarchy** → provide/inject
+- **Global config** → app.config.globalProperties
+
+### 3. Composables
+
+**Create reusable logic:**
+```javascript
+// composables/useCounter.js
+import { ref, computed } from 'vue'
+
+export function useCounter(initial = 0) {
+  const count = ref(initial)
+  const doubled = computed(() => count.value * 2)
+
+  function increment() {
+    count.value++
+  }
+
+  return { count, doubled, increment }
+}
+
+// Usage in component
+const { count, doubled, increment } = useCounter(10)
+```
+
+### 4. Pinia Store
+
+**Create feature store:**
+```javascript
+// stores/auth.js
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+
+export const useAuthStore = defineStore('auth', () => {
+  // State
+  const user = ref(null)
+  const token = ref(null)
+
+  // Getters
+  const isAuthenticated = computed(() => !!token.value)
+
+  // Actions
+  async function login(credentials) {
+    const response = await api.login(credentials)
+    user.value = response.user
+    token.value = response.token
+  }
+
+  function logout() {
+    user.value = null
+    token.value = null
+  }
+
+  return { user, token, isAuthenticated, login, logout }
+})
+```
+
+### 5. Common Patterns
+
+**Fetch data:**
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const data = ref(null)
+const loading = ref(true)
+const error = ref(null)
+
+onMounted(async () => {
+  try {
+    data.value = await api.getData()
+  } catch (err) {
+    error.value = err
+  } finally {
+    loading.value = false
+  }
+})
+</script>
+
+<template>
+  <div v-if="loading">Loading...</div>
+  <div v-else-if="error">Error: {{ error.message }}</div>
+  <div v-else>{{ data }}</div>
+</template>
+```
+
+**Form handling:**
+```vue
+<script setup>
+import { reactive, computed } from 'vue'
+
+const form = reactive({
+  email: '',
+  password: ''
+})
+
+const errors = reactive({
+  email: '',
+  password: ''
+})
+
+const isValid = computed(() =>
+  form.email && form.password && !errors.email && !errors.password
+)
+
+function validateEmail() {
+  errors.email = form.email.includes('@') ? '' : 'Invalid email'
+}
+
+async function submit() {
+  if (!isValid.value) return
+  await api.login(form)
+}
+</script>
+
+<template>
+  <form @submit.prevent="submit">
+    <input
+      v-model="form.email"
+      @blur="validateEmail"
+      :class="{ error: errors.email }"
+    >
+    <span v-if="errors.email">{{ errors.email }}</span>
+
+    <input v-model="form.password" type="password">
+
+    <button :disabled="!isValid">Login</button>
+  </form>
+</template>
+```
+
+## For /dev-review
+
+When reviewing Vue 3 code:
+
+**Component Quality:**
+- [ ] Uses `<script setup>` (not Options API)
+- [ ] Props properly typed (TypeScript or PropType)
+- [ ] Emits properly defined
+- [ ] Component names are PascalCase
+- [ ] SFC order: script → template → style
+
+**Composition API:**
+- [ ] Composables follow "use*" naming
+- [ ] No conditional composable calls
+- [ ] Composables called at top level of setup
+- [ ] Reactive values returned from composables
+- [ ] Cleanup handled (watchers, listeners)
+
+**Reactivity:**
+- [ ] ref() used for primitives
+- [ ] reactive() used for objects
+- [ ] .value accessed in script (not template)
+- [ ] No destructuring reactive without toRefs
+- [ ] No reassigning reactive objects
+- [ ] computed() for derived state
+- [ ] No complex logic in template
+
+**Template:**
+- [ ] v-for has unique :key
+- [ ] No v-for + v-if on same element
+- [ ] v-bind/v-on use shorthands (: and @)
+- [ ] No inline objects/arrays (causes re-renders)
+- [ ] Proper event naming (kebab-case)
+
+**State Management:**
+- [ ] Appropriate scope (local, composable, store)
+- [ ] Props not mutated directly
+- [ ] Emits used for child → parent
+- [ ] Pinia stores follow composition pattern
+- [ ] No Vuex (use Pinia)
+
+**Performance:**
+- [ ] Heavy components lazy loaded
+- [ ] Large lists use stable keys
+- [ ] v-memo used for expensive items
+- [ ] No unnecessary reactivity (shallowRef/shallowReactive)
+- [ ] Watchers cleaned up
+
+**TypeScript:**
+- [ ] Props typed properly
+- [ ] Emits typed
+- [ ] Composables return types defined
+- [ ] No excessive use of any
+
+## Integration with Other Stacks
+
+**Vue + Nuxt:**
+- Follow Nuxt conventions (pages/, composables/, server/)
+- Use auto-imports
+- Use Nuxt composables (useAsyncData, useFetch, etc.)
+- Follow SSR guidelines
+
+**Vue + Vite:**
+- Fast dev server with HMR
+- Use Vite plugins
+- Leverage Vite's optimized build
+
+**Vue + TypeScript:**
+- Use `<script setup lang="ts">`
+- Define props with interface
+- Type emits and composables
+- Use generic components
+
+**Vue + Pinia:**
+- Composition-style stores
+- TypeScript support built-in
+- DevTools integration
+- Hot module replacement
+
+## Common Gotchas
+
+1. **Ref .value**: Forgetting .value in script, adding .value in template
+2. **Destructuring Reactivity**: Losing reactivity when destructuring reactive()
+3. **Conditional Composables**: Calling composables inside if/loops
+4. **Props Mutation**: Mutating props directly instead of emitting
+5. **v-for Key**: Using index or missing key entirely
+6. **v-for + v-if**: Combining on same element (use computed filter)
+7. **Template Refs**: Accessing $refs before onMounted
+8. **Async Setup**: Can't use async setup() without Suspense
+
+## Vue 3 Features
+
+**Composition API:**
+- setup() and <script setup>
+- Composables for logic reuse
+- Better TypeScript support
+- More flexible code organization
+
+**New APIs:**
+- Teleport (render outside component hierarchy)
+- Fragments (multiple root nodes)
+- Suspense (async component loading)
+- defineAsyncComponent (lazy loading)
+
+**Performance:**
+- Faster reactivity system (Proxy-based)
+- Smaller bundle size
+- Better tree-shaking
+- Optimized virtual DOM
+
+## Resources
+
+- [Vue 3 Docs](https://vuejs.org) - Official documentation
+- [Vue DevTools](https://devtools.vuejs.org) - Browser extension
+- [Pinia](https://pinia.vuejs.org) - Official state management
+- [Vue Router](https://router.vuejs.org) - Official router
+- [Vite](https://vitejs.dev) - Recommended build tool