vue-debug-guides

Overview of vue-debug-guides skill

What vue-debug-guides skill is for

vue-debug-guides is a Vue 3 troubleshooting skill focused on diagnosing runtime bugs, warnings, async loading failures, reactivity surprises, and SSR or hydration mismatches. It is most useful when you already have a broken or confusing behavior and need a targeted debugging path faster than a generic “help me debug Vue” prompt.

Who should use vue-debug-guides

Best fit readers are developers working in real Vue 3 apps with symptoms such as unexpected re-renders, refs not updating, duplicated event handlers, async component failures, route-loading mistakes, or DOM timing issues. It is especially useful for teams that want issue-specific guidance instead of broad framework tutorials.

Real job-to-be-done

The real job is not learning Vue from scratch. It is narrowing a vague bug report into the likely Vue-specific pitfall, then applying the right fix pattern with fewer false starts. The value of vue-debug-guides is that it maps common symptoms to concrete gotchas and corrective examples.

What makes this different from a normal prompt

A normal prompt often produces broad debugging advice. The vue-debug-guides skill is better when the problem likely depends on Vue semantics: reactivity rules, computed constraints, async component behavior, Suspense, keep-alive, fallthrough attrs, event modifiers, nextTick, or script setup limitations. The repository is organized around these exact failure modes, so outputs can be more specific and more actionable.

Strongest adoption reasons

The strongest reason to install vue-debug-guides is coverage of high-friction edge cases that are easy to misdiagnose from app symptoms alone. The reference set includes practical topics like async component error handling, why defineAsyncComponent should not be used for Vue Router routes, why Suspense can suppress async component loading and error options, and why component refs can break across keep-alive reactivation.

What it does not replace

This skill is not a substitute for Vue fundamentals, app profiling tools, or framework documentation. If your need is architecture advice, style conventions, or broad “best practices,” the repo itself points to vue-best-practices as a better fit. Use vue-debug-guides for Debugging when you already have a failure, warning, or non-obvious behavior to explain and fix.

How to Use vue-debug-guides skill

Install context for vue-debug-guides

Install from the vuejs-ai/skills repository in whatever skill-enabled environment you use. A common pattern is:

npx skills add vuejs-ai/skills --skill vue-debug-guides

The repository evidence does not show a built-in install command inside SKILL.md, so directory users should treat the skill as content-first: install it into your agent environment, then invoke it with a concrete Vue debugging task.

Start with the right files first

Read skills/vue-debug-guides/SKILL.md first to understand the symptom-to-reference map. Then open the specific files under reference/ that match your issue. Good first reads include:

• reference/async-component-error-handling.md
• reference/async-component-suspense-control.md
• reference/async-component-vue-router.md
• reference/cleanup-side-effects.md
• reference/component-ref-requires-defineexpose.md
• reference/dom-update-timing-nexttick.md
• reference/computed-no-side-effects.md
• reference/attrs-event-listener-merging.md

This repo is reference-heavy, so adoption is easier if you treat it like a decision tree, not like a single linear guide.

Match your bug to the closest symptom

The best vue-debug-guides usage starts with symptom framing. Instead of asking “debug my component,” describe the observable failure:

• “Ref updates in script but template stays stale”
• “Async route component never shows my loading UI”
• “Hydration warning appears only on first load”
• “Click handler fires twice on wrapped button”
• “Method on child component ref becomes undefined after tab switch”

That symptom-first framing helps the skill route you toward the relevant gotcha instead of returning generic Vue advice.

What input the skill needs to work well

Provide enough context for Vue-specific diagnosis:

• Vue version and major ecosystem pieces: Vue Router, Pinia, SSR/Nuxt, Vite
• Whether the issue is client-only, SSR-only, or hydration-only
• Minimal component or route code
• Exact warning or error text
• Expected behavior vs actual behavior
• Whether Suspense, keep-alive, async components, or script setup are involved

Without those details, the skill can still suggest likely causes, but output quality drops because many Vue bugs share similar symptoms.

Turn a rough request into a strong prompt

Weak prompt:

Use vue-debug-guides to debug why my Vue component is broken.

Stronger prompt:

Use vue-debug-guides to diagnose a Vue 3 issue. In a route component loaded with Vue Router, I wrapped the page in defineAsyncComponent and added loadingComponent, but the loading state never appears and navigation feels inconsistent. We use Vue Router 4 and Vite. Explain the likely mistake, show the correct route lazy-loading pattern, and tell me when Suspense would change the behavior again.

Why this works: it includes the symptom, the suspect API, the ecosystem, and the desired output format.

Practical workflow for vue-debug-guides usage

1. Describe the symptom in one sentence.
2. Paste the smallest code sample that still reproduces it.
3. Ask the agent to identify the most likely Vue-specific rule being violated.
4. Ask for one corrected version, not five alternatives.
5. If needed, ask for a short checklist to verify the fix in DevTools or the browser console.

This keeps the skill focused on diagnosis and repair instead of drifting into generic refactoring.

High-value reference paths in this repo

Several reference files point to issues that often waste debugging time:

• async-component-vue-router.md: route lazy loading mistakes
• async-component-suspense-control.md: why loadingComponent and errorComponent seem ignored
• async-component-keepalive-ref-issue.md: disappearing refs after reactivation
• attrs-event-listener-merging.md: duplicate click behavior from fallthrough listeners
• computed-no-side-effects.md: hidden mutations inside computed getters
• dom-update-timing-nexttick.md: DOM reads happening before Vue flushes updates

If your bug sits near one of these boundaries, vue-debug-guides install is likely worth it because generic prompts commonly miss these details.

Tips that materially improve output quality

Ask the agent to do three things in order:

1. Name the likely Vue rule or gotcha.
2. Point to the exact code line or pattern that triggers it.
3. Produce the smallest safe fix.

That structure prevents long speculative answers and makes the skill behave more like a debugging assistant than a tutor.

When to use this instead of general Vue help

Use vue-debug-guides guide mode when the bug likely depends on framework behavior rather than your business logic. If your issue is “API returns wrong data,” this skill is not the main tool. If your issue is “watcher fires unexpectedly,” “ref is undefined,” “transition lags,” or “route component loading behaves strangely,” it is much better aligned.

vue-debug-guides skill FAQ

Is vue-debug-guides good for beginners

Yes, if the beginner already has a concrete bug. The references are practical and example-driven. But it is not the best first resource for learning Vue concepts from zero, because the material is organized around failure cases rather than a teaching sequence.

What kinds of bugs does vue-debug-guides cover best

vue-debug-guides is strongest on Vue 3 runtime debugging: reactivity edge cases, computed misuse, watcher behavior, async component failures, DOM update timing, event and attrs merging, and component lifecycle interactions such as keep-alive or Suspense.

Does it help with SSR and hydration issues

Yes. The skill description explicitly includes SSR and hydration bugs. That matters because hydration failures often need Vue-specific reasoning, not just generic frontend debugging. You should still provide the exact warning text and clarify whether the mismatch happens only in production or only on first render.

How is this different from ordinary prompting

Ordinary prompting often gives “check your state” advice. The vue-debug-guides skill gives more value when the answer depends on known Vue gotchas, such as top-level template ref unwrapping rules, batched updates in the same tick, or route component loading patterns that differ from normal async components.

Should I use it for Vue Router issues

Yes, if the router issue intersects with component loading, transitions, or render timing. One of the most useful references explains that route components should use dynamic imports directly instead of defineAsyncComponent, which is a common source of confusion.

When is vue-debug-guides a poor fit

It is a poor fit for design systems, app architecture, state modeling, or generic JavaScript errors unrelated to Vue semantics. It is also not the best tool when you need coding standards more than debugging guidance.

How to Improve vue-debug-guides skill

Give vue-debug-guides a reproducible symptom

The fastest way to improve results is to provide a minimal reproduction. Include the smallest component, route config, or composable that still shows the issue. This helps the skill map your case to an existing reference instead of guessing from a large codebase.

Name the Vue features in play

Mention whether your code uses:

• script setup
• defineAsyncComponent
• Suspense
• keep-alive
• Vue Router
• SSR or hydration
• composables, watchers, or computed values

These details sharply narrow the search space and often point directly to a matching guide.

Include exact warnings, not paraphrases

A paraphrased “Vue says something about hydration” is much less useful than the exact console message. The skill is built around specific classes of mistakes, so the raw warning text improves match quality and reduces incorrect fixes.

Ask for diagnosis before refactoring

A common failure mode is requesting a rewrite too early. Better prompt:

Use vue-debug-guides to identify the likely Vue rule being broken here, explain why this symptom happens, and then show the smallest fix.

That sequence tends to produce cleaner answers than asking for a full refactor first.

Compare expected and actual behavior

Do not just paste code. State:

• what you expected
• what actually happened
• whether it is consistent or intermittent
• whether it changed after adding a Vue feature like Suspense or keep-alive

Those comparisons help the skill distinguish between a logic bug and a framework interaction bug.

Iterate after the first answer

If the first output is close but not enough, ask a tighter follow-up:

• “Now assume this component is inside <Suspense>.”
• “Now account for SSR hydration.”
• “Now explain why the event fires twice.”
• “Now show how to verify the fix with Vue DevTools.”

This is the best way to get deeper value from vue-debug-guides for Debugging without broadening the request too much.

Watch for common failure modes

Results are weaker when you:

• paste too much unrelated code
• omit the error message
• hide whether routing or SSR is involved
• ask for “all possible causes”
• mix debugging, refactoring, and architecture goals in one request

Keep the task narrow. This skill works best when the question is diagnostic and evidence-based.

Use the reference folder as a follow-up source

After the agent identifies a likely cause, open the referenced markdown file and compare your code against its “bad” and “good” patterns. In this repo, the reference/ files are the real depth layer. The best vue-debug-guides guide workflow is often: identify likely topic, read one matching file, apply the fix, then return for a second-pass prompt if needed.