Vue Debug Guides
Stop Vue 3 list and route transitions from silently failing when AutoAnimate or similar libs cannot see DOM reuse.
Overview
vue-debug-guides is an agent skill for the Build phase that teaches Vue 3 `:key` patterns so AutoAnimate and similar libraries detect changes when DOM reuse blocks animations.
Install
npx skills add https://github.com/hyf0/vue-skills --skill vue-debug-guidesWhat is this skill?
- Explains why Vue reuses DOM nodes and blocks transition detection
- Task checklist: key on animating children, unique keys, `$route.fullPath` on router-view
- Contrasts bad vs good patterns for text, images, and route changes
- Targets AutoAnimate and MEDIUM-impact rerender gotchas
- Vue 3 composition API (`script setup`) examples
- 4-item task checklist for keys and router-view
- Tagged impact: MEDIUM for animation detection
Adoption & trust: 13.6k installs on skills.sh; 2.5k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Vue UI updates text, images, or routes but transition libraries never fire because Vue reuses the same DOM element.
Who is it for?
Vue 3 apps using AutoAnimate or route transitions where content changes but animations stay dead.
Skip if: Non-Vue stacks, CSS-only transitions with no DOM-reuse issue, or performance tuning without animation requirements.
When should I use this skill?
Vue 3 UI uses AutoAnimate or route/content transitions and updates happen without visible animation.
What do I get? / Deliverables
Keyed children and router views force proper re-renders so parent `v-auto-animate` containers animate list, media, and route changes reliably.
- Keyed template patterns for lists, media, and router-view
- Correct parent/child `v-auto-animate` structure
Recommended Skills
Journey fit
How it compares
Use for Vue-specific DOM reuse gotchas instead of generic CSS animation docs that ignore Vue’s reconciliation.
Common Questions / FAQ
Who is vue-debug-guides for?
Solo and indie builders shipping Vue 3 frontends who use AutoAnimate or route-level motion and need a fast, correct `:key` fix.
When should I use vue-debug-guides?
During Build (frontend) when list items, images, or `router-view` content changes without animating; also when debugging transition regressions before Ship review.
Is vue-debug-guides safe to install?
It is documentation-style guidance with no runtime hooks; review the Security Audits panel on this Prism page before adding any skill from the repo.
SKILL.md
READMESKILL.md - Vue Debug Guides
# Use Key Attribute to Force Re-render Animations **Impact: MEDIUM** - Vue optimizes performance by reusing DOM elements when possible. However, this optimization can prevent animation libraries (like AutoAnimate) from detecting changes, because the element is updated in place rather than re-created. Adding a `:key` attribute forces Vue to treat changed elements as new, triggering proper animations. ## Task Checklist - [ ] Add `:key` to elements that should animate when their content changes - [ ] Use unique, changing values for keys (not indices) - [ ] For route transitions, add `:key="$route.fullPath"` to `<router-view>` - [ ] Apply `v-auto-animate` to the parent element of keyed children **Problematic Code:** ```vue <template> <!-- BAD: Text changes but no animation occurs --> <div v-auto-animate> <p>{{ message }}</p> <!-- No key - element is reused --> </div> <!-- BAD: Image source changes but no animation --> <div v-auto-animate> <img :src="imageUrl" /> <!-- No key - element is reused --> </div> <!-- BAD: Route changes don't animate --> <router-view v-auto-animate /> <!-- No key --> </template> <script setup> import { ref } from 'vue' const message = ref('Hello') const imageUrl = ref('/images/photo1.jpg') // Changing these won't trigger animations because // Vue updates the existing elements rather than replacing them </script> ``` **Correct Code:** ```vue <template> <!-- GOOD: Key forces re-render, triggering animation --> <div v-auto-animate> <p :key="message">{{ message }}</p> </div> <!-- GOOD: Image animates when source changes --> <div v-auto-animate> <img :key="imageUrl" :src="imageUrl" /> </div> <!-- GOOD: Route changes animate properly --> <router-view :key="$route.fullPath" v-auto-animate /> </template> <script setup> import { ref } from 'vue' const message = ref('Hello') const imageUrl = ref('/images/photo1.jpg') // Now changing these will trigger animations function updateMessage() { message.value = 'World' // Triggers enter animation for new <p> } </script> ``` ## Why This Works When Vue sees a `:key` change: 1. It considers the old element and new element as different 2. The old element is removed (triggering leave animation) 3. A new element is created (triggering enter animation) Without `:key`: 1. Vue sees the same element type in the same position 2. It updates the element's properties in place 3. No DOM addition/removal occurs, so no animation triggers ## Common Use Cases ### Animating Text Content Changes ```vue <template> <div v-auto-animate> <h1 :key="title">{{ title }}</h1> <p :key="description">{{ description }}</p> </div> </template> ``` ### Animating Dynamic Components ```vue <template> <div v-auto-animate> <component :is="currentComponent" :key="currentComponent" /> </div> </template> ``` ### Animating Route Transitions ```vue <template> <router-view v-slot="{ Component, route }"> <div v-auto-animate> <component :is="Component" :key="route.fullPath" /> </div> </router-view> </template> ``` ## With Vue's Built-in Transition The same principle applies to Vue's `<Transition>` component: ```vue <template> <!-- GOOD: Key triggers transition on content change --> <Transition name="fade" mode="out-in"> <p :key="message">{{ message }}</p> </Transition> <!-- GOOD: Different keys for conditional content --> <Transition name="fade" mode="out-in"> <div v-if="isLoading" key="loading">Loading...</div> <div v-else key="content">{{ content }}</div> </Transition> </template> ``` ## Caution: Performance Implications Using `:key` forces full component re-creation. For frequently changin