debug:vue

What this skill does

# Vue.js Debugging Guide

A systematic approach to debugging Vue.js 3 applications, covering common error patterns, debugging tools, and resolution strategies.

## Common Error Patterns

### 1. Reactivity Not Working

**Symptoms:**
- Data changes but UI does not update
- Computed properties return stale values
- Watch callbacks not firing

**Common Causes:**
```javascript
// WRONG: Adding new properties to reactive object
const state = reactive({ count: 0 })
state.newProp = 'value'  // Not reactive in Vue 2, works in Vue 3 with Proxy

// WRONG: Destructuring reactive objects
const { count } = reactive({ count: 0 })  // count is NOT reactive

// WRONG: Replacing entire reactive object
let state = reactive({ count: 0 })
state = reactive({ count: 1 })  // Lost reactivity connection

// WRONG: Using ref without .value
const count = ref(0)
count = 5  // Wrong! Use count.value = 5
```

**Solutions:**
```javascript
// Use toRefs for destructuring
const state = reactive({ count: 0 })
const { count } = toRefs(state)  // count.value is reactive

// Use ref for primitives
const count = ref(0)
count.value++  // Correct

// Use shallowRef for large objects that don't need deep reactivity
const largeData = shallowRef({ /* big object */ })

// Force reactivity update
import { triggerRef } from 'vue'
triggerRef(myShallowRef)
```

### 2. Component Not Updating

**Symptoms:**
- Props change but component doesn't re-render
- Parent state updates don't propagate to children
- v-for lists don't update correctly

**Debugging Steps:**
```javascript
// 1. Check if prop is reactive
watch(() => props.myProp, (newVal) => {
  console.log('Prop changed:', newVal)
}, { immediate: true })

// 2. Verify key attribute on v-for
<template>
  <!-- WRONG: index as key for dynamic lists -->
  <div v-for="(item, index) in items" :key="index">

  <!-- CORRECT: unique identifier -->
  <div v-for="item in items" :key="item.id">
</template>

// 3. Check for prop mutation (anti-pattern)
// Props should be immutable - emit events instead
emit('update:modelValue', newValue)
```

### 3. Pinia Store Issues

**Symptoms:**
- Store state not updating across components
- Actions not triggering reactivity
- Getters returning stale data

**Common Problems:**
```javascript
// WRONG: Destructuring store state
const store = useMyStore()
const { count } = store  // NOT reactive!

// CORRECT: Use storeToRefs
const store = useMyStore()
const { count } = storeToRefs(store)  // Reactive

// WRONG: Mutating state directly outside actions
store.count++  // Works but bypasses devtools tracking

// CORRECT: Use actions or $patch
store.increment()  // Action
store.$patch({ count: store.count + 1 })  // $patch
```

**Debugging Pinia:**
```javascript
// Enable Pinia devtools tracking
import { createPinia } from 'pinia'
const pinia = createPinia()

// Subscribe to state changes
store.$subscribe((mutation, state) => {
  console.log('Mutation:', mutation.type, mutation.storeId)
  console.log('New state:', state)
})

// Subscribe to actions
store.$onAction(({ name, args, after, onError }) => {
  console.log(`Action ${name} called with:`, args)
  after((result) => console.log(`${name} returned:`, result))
  onError((error) => console.error(`${name} failed:`, error))
})
```

### 4. Computed Property Caching Issues

**Symptoms:**
- Computed returns same value despite dependency changes
- Infinite loops in computed properties
- Performance issues with computed

**Solutions:**
```javascript
// Check dependencies are reactive
const computed1 = computed(() => {
  // This won't update if nonReactiveValue changes
  return someRef.value + nonReactiveValue
})

// Avoid side effects in computed
// WRONG:
const bad = computed(() => {
  someRef.value = 'changed'  // Side effect!
  return otherRef.value
})

// Debug computed dependencies
const myComputed = computed(() => {
  console.log('Computed recalculating...')
  return expensiveOperation(dep1.value, dep2.value)
})
```

### 5. Teleport/Suspense Issues

**Teleport Problems:**
```html
<!-- Ensure target exists before Teleport mounts -->
<template>
  <!-- WRONG: target might not exist -->
  <Teleport to="#modal-container">
    <Modal />
  </Teleport>

  <!-- CORRECT: conditional render -->
  <Teleport v-if="isMounted" to="#modal-container">
    <Modal />
  </Teleport>
</template>

<script setup>
import { ref, onMounted } from 'vue'
const isMounted = ref(false)
onMounted(() => { isMounted.value = true })
</script>
```

**Suspense Problems:**
```html
<!-- Handle errors in Suspense -->
<template>
  <Suspense>
    <template #default>
      <AsyncComponent />
    </template>
    <template #fallback>
      <LoadingSpinner />
    </template>
  </Suspense>
</template>

<script setup>
import { onErrorCaptured, ref } from 'vue'

const error = ref(null)
onErrorCaptured((err) => {
  error.value = err
  return false  // Stop propagation
})
</script>
```

### 6. SSR Hydration Mismatches

**Symptoms:**
- Console warning: "Hydration mismatch"
- Content flickers on page load
- Different content between server and client

**Common Causes and Solutions:**
```javascript
// WRONG: Browser-only code in setup
const width = window.innerWidth  // Fails on server

// CORRECT: Use onMounted for browser APIs
const width = ref(0)
onMounted(() => {
  width.value = window.innerWidth
})

// CORRECT: Use ClientOnly component (Nuxt)
<template>
  <ClientOnly>
    <BrowserOnlyComponent />
  </ClientOnly>
</template>

// Check for SSR vs client
const isClient = typeof window !== 'undefined'

// Use useId() for consistent IDs
import { useId } from 'vue'
const id = useId()  // Same on server and client
```

## Debugging Tools

### Vue DevTools

**Installation:**
- Chrome: [Vue.js devtools](https://chrome.google.com/webstore/detail/vuejs-devtools/)
- Firefox: [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)

**Key Features:**
1. **Components Tab**: Inspect component hierarchy, props, data, computed
2. **Pinia Tab**: View store state, actions, mutations
3. **Timeline Tab**: Track events, mutations, and performance
4. **Routes Tab**: Debug Vue Router (if using)

**DevTools Tips:**
```javascript
// Access component instance in console
// Select component in DevTools, then in console:
$vm  // Current component instance
$vm.someMethod()  // Call methods
$vm.someData  // Access data

// Inspect from DOM element
// Right-click element > Inspect > Console:
$0.__vueParentComponent  // Parent component
```

### Console Debugging

```javascript
// Strategic console.log placement
export default {
  setup() {
    const state = reactive({ count: 0 })

    // Log reactive state changes
    watch(
      () => ({ ...state }),
      (newState, oldState) => {
        console.log('State changed:', { old: oldState, new: newState })
      },
      { deep: true }
    )

    return { state }
  }
}

// Use console.table for arrays/objects
console.table(items.value)

// Use console.trace for call stack
function problematicFunction() {
  console.trace('Called from:')
}

// Group related logs
console.group('Component Mount')
console.log('Props:', props)
console.log('State:', state)
console.groupEnd()
```

### Debugger Statement

```javascript
// Pause at specific points
function handleClick() {
  debugger  // Execution pauses here
  // Inspect scope, call stack, evaluate expressions
  processData()
}

// Conditional debugging
watch(count, (val) => {
  if (val > 10) {
    debugger  // Only pause when condition met
  }
})
```

### Vite Dev Server

```bash
# Enable verbose logging
vite --debug

# Check for HMR issues
vite --force  # Clear cache

# Common vite.config.js debugging options
export default defineConfig({
  server: {
    hmr: {
      overlay: true  // Show errors as overlay
    }
  },
  build: {
    sourcemap: true  // Enable source maps
  }
})
```

### vue-tsc Type Checking

```bash
# Run type checking
npx vue-tsc --noEmit

# Watch mode
npx vue-tsc --noEmit --watch

# Check specific files
npx vue-tsc --noEm