vue-debug-guides_skill

Overview

This skill provides focused debugging guidance for Vue 3 runtime errors, warnings, async failures, and SSR/hydration problems. It organizes common failure modes across reactivity, computed/watchers, components, templates, lifecycle, and async/SSR flows to speed diagnosis and fixes. Use it to locate root causes and apply concise, actionable remedies.

How this skill works

The skill inspects common failure categories and maps symptoms to concrete causes and fixes: unexpected re-renders, ref/value access mistakes, computed/watch pitfalls, template/ref/props issues, event/slot/attrs gotchas, lifecycle and SSR mismatches, and async component failures. It points to targeted checks (e.g., missing .value, destructuring reactive objects, watcher cleanup, defineEmits/defineProps placement, SSR hydration order) and recommends small repro steps and instrumentation to confirm fixes.

When to use it

• You see unexplained re-renders or stale state updates.
• Hydration or SSR mismatches appear in production or during client takeover.
• Watchers or watchEffect produce stale values or race with async code.
• Template runtime errors (cannot read property X) or v-for/v-if rendering bugs.
• Async component load failures, timeouts, or unexpected lifecycle behavior.

Best practices

• Reproduce the bug in the smallest component possible to isolate scope.
• Enable Vue devtools and add focused logging around reactive/read/write points.
• Avoid side effects inside computed/template expressions and use cleanup handlers for async watchers.
• Prefer defineEmits/defineProps at top-level in script setup and use defineExpose before awaiting async setup code.
• For SSR/hydration issues, compare server HTML vs. client render and use synchronous registration for lifecycle/provide calls.

Example use cases

• Trace a ref that doesn’t update because code forgot .value access or destructured a reactive and lost reactivity.
• Fix a computed property that stops updating after conditional branching or mutates its dependency array.
• Correct a watcher race where an awaited async task overwrote newer data—add cancellation/cleanup.
• Resolve SSR hydration mismatch by checking mount-time DOM differences and lifecycle ordering.
• Handle async component network failures with proper error/timeout handlers and fallbacks.