devskill 2.0.2

package/skills/vue-router-best-practices/reference/router-simple-routing-cleanup.md

@@ -0,0 +1,209 @@
+---
+title: Simple Hash Routing Requires Event Listener Cleanup
+impact: MEDIUM
+impactDescription: When implementing basic routing without Vue Router, forgetting to remove hashchange listeners causes memory leaks and multiple handler execution
+type: gotcha
+tags: [vue3, routing, events, memory-leak, cleanup]
+---
+
+# Simple Hash Routing Requires Event Listener Cleanup
+
+**Impact: MEDIUM** - When implementing basic client-side routing without Vue Router (using hash-based routing with `hashchange` events), you must clean up event listeners when the component unmounts. Failure to do so causes memory leaks and can result in multiple handlers firing after the component is recreated.
+
+## Task Checklist
+
+- [ ] Store event listener reference for cleanup
+- [ ] Use onUnmounted to remove event listener
+- [ ] Consider using Vue Router instead for production apps
+- [ ] Test component mount/unmount cycles
+
+## The Problem
+
+```vue
+<script setup>
+import { ref, computed } from 'vue'
+import Home from './Home.vue'
+import About from './About.vue'
+
+const routes = {
+  '/': Home,
+  '/about': About
+}
+
+const currentPath = ref(window.location.hash)
+
+// BUG: Event listener is never removed!
+// Each time this component mounts, a NEW listener is added
+// After mounting 5 times, you have 5 listeners running
+window.addEventListener('hashchange', () => {
+  currentPath.value = window.location.hash
+})
+
+const currentView = computed(() => {
+  return routes[currentPath.value.slice(1) || '/']
+})
+</script>
+```
+
+**What happens:**
+1. Component mounts, adds listener
+2. Component unmounts (e.g., route change, v-if toggle)
+3. Component mounts again, adds ANOTHER listener
+4. Now TWO listeners respond to each hash change
+5. Eventually causes performance issues and memory leaks
+
+## Solution: Proper Cleanup with onUnmounted
+
+```vue
+<script setup>
+import { ref, computed, onUnmounted } from 'vue'
+import Home from './Home.vue'
+import About from './About.vue'
+import NotFound from './NotFound.vue'
+
+const routes = {
+  '/': Home,
+  '/about': About
+}
+
+const currentPath = ref(window.location.hash)
+
+// Store handler reference for cleanup
+function handleHashChange() {
+  currentPath.value = window.location.hash
+}
+
+// Add listener
+window.addEventListener('hashchange', handleHashChange)
+
+// CRITICAL: Remove listener on unmount
+onUnmounted(() => {
+  window.removeEventListener('hashchange', handleHashChange)
+})
+
+const currentView = computed(() => {
+  return routes[currentPath.value.slice(1) || '/'] || NotFound
+})
+</script>
+```
+
+## Solution: Using Options API
+
+```vue
+<script>
+import Home from './Home.vue'
+import About from './About.vue'
+import NotFound from './NotFound.vue'
+
+const routes = {
+  '/': Home,
+  '/about': About
+}
+
+export default {
+  data() {
+    return {
+      currentPath: window.location.hash
+    }
+  },
+
+  computed: {
+    currentView() {
+      return routes[this.currentPath.slice(1) || '/'] || NotFound
+    }
+  },
+
+  mounted() {
+    // Store bound handler for cleanup
+    this.hashHandler = () => {
+      this.currentPath = window.location.hash
+    }
+    window.addEventListener('hashchange', this.hashHandler)
+  },
+
+  beforeUnmount() {
+    // Clean up
+    window.removeEventListener('hashchange', this.hashHandler)
+  }
+}
+</script>
+```
+
+## Solution: Composable for Reusable Hash Routing
+
+```javascript
+// composables/useHashRouter.js
+import { ref, computed, onUnmounted } from 'vue'
+
+export function useHashRouter(routes, notFoundComponent = null) {
+  const currentPath = ref(window.location.hash)
+
+  function handleHashChange() {
+    currentPath.value = window.location.hash
+  }
+
+  // Setup
+  window.addEventListener('hashchange', handleHashChange)
+
+  // Cleanup - handled automatically when component unmounts
+  onUnmounted(() => {
+    window.removeEventListener('hashchange', handleHashChange)
+  })
+
+  const currentView = computed(() => {
+    const path = currentPath.value.slice(1) || '/'
+    return routes[path] || notFoundComponent
+  })
+
+  function navigate(path) {
+    window.location.hash = path
+  }
+
+  return {
+    currentPath,
+    currentView,
+    navigate
+  }
+}
+```
+
+```vue
+<!-- Usage -->
+<script setup>
+import { useHashRouter } from '@/composables/useHashRouter'
+import Home from './Home.vue'
+import About from './About.vue'
+import NotFound from './NotFound.vue'
+
+const { currentView } = useHashRouter({
+  '/': Home,
+  '/about': About
+}, NotFound)
+</script>
+
+<template>
+  <component :is="currentView" />
+</template>
+```
+
+## When to Use Simple Routing vs Vue Router
+
+| Use Simple Hash Routing | Use Vue Router |
+|------------------------|----------------|
+| Learning/prototyping | Production apps |
+| Very simple apps (2-3 pages) | Nested routes needed |
+| No build step available | Navigation guards needed |
+| Bundle size critical | Lazy loading needed |
+| Static hosting only | History mode (clean URLs) |
+
+## Key Points
+
+1. **Always clean up event listeners** - Use onUnmounted or beforeUnmount
+2. **Store handler reference** - Anonymous functions can't be removed
+3. **Consider Vue Router for real apps** - It handles cleanup automatically
+4. **Test unmount scenarios** - v-if toggling, hot module replacement
+5. **Composables help encapsulate cleanup logic** - Reusable and automatic
+
+## Reference
+- [Vue.js Routing Documentation](https://vuejs.org/guide/scaling-up/routing.html)
+- [Vue Router Official Library](https://router.vuejs.org/)

package/skills/vue-router-best-practices/reference/router-use-vue-router-for-production.md

@@ -0,0 +1,183 @@
+---
+title: Use Vue Router Library for Production Applications
+impact: LOW
+impactDescription: Simple hash routing lacks essential features for production SPAs; Vue Router provides navigation guards, lazy loading, and proper history management
+type: best-practice
+tags: [vue3, vue-router, spa, production, architecture]
+---
+
+# Use Vue Router Library for Production Applications
+
+**Impact: LOW** - While you can implement basic routing with hash changes and dynamic components, the official Vue Router library should be used for any production single-page application. It provides essential features like navigation guards, nested routes, lazy loading, and proper browser history integration that are tedious and error-prone to implement manually.
+
+## Task Checklist
+
+- [ ] Install Vue Router for production SPAs
+- [ ] Use simple routing only for learning or tiny prototypes
+- [ ] Leverage built-in features: guards, lazy loading, meta fields
+- [ ] Consider router-based state and data loading patterns
+
+## When Simple Routing is Acceptable
+
+```vue
+<!-- Only for: learning, prototypes, or micro-apps with 2-3 pages -->
+<script setup>
+import { ref, computed } from 'vue'
+import Home from './Home.vue'
+import About from './About.vue'
+
+const routes = { '/': Home, '/about': About }
+const currentPath = ref(window.location.hash.slice(1) || '/')
+
+window.addEventListener('hashchange', () => {
+  currentPath.value = window.location.hash.slice(1) || '/'
+})
+
+const currentView = computed(() => routes[currentPath.value])
+</script>
+
+<template>
+  <nav>
+    <a href="#/">Home</a>
+    <a href="#/about">About</a>
+  </nav>
+  <component :is="currentView" />
+</template>
+```
+
+## Why Vue Router for Production
+
+### Features You'd Have to Implement Manually
+
+| Feature | Simple Routing | Vue Router |
+|---------|---------------|------------|
+| Navigation guards | Manual, error-prone | Built-in, composable |
+| Nested routes | Complex to implement | Native support |
+| Route params | Parse manually | Automatic extraction |
+| Lazy loading | DIY with dynamic imports | Built-in with code splitting |
+| History mode (clean URLs) | Requires server config + manual | Built-in |
+| Scroll behavior | Manual | Configurable |
+| Route transitions | DIY | Integrated with Transition |
+| Active link styling | Manual class toggling | `router-link-active` class |
+| Programmatic navigation | `location.hash = ...` | `router.push()`, `router.replace()` |
+| Route meta fields | N/A | Built-in |
+
+## Production Setup with Vue Router
+
+```javascript
+// router/index.js
+import { createRouter, createWebHistory } from 'vue-router'
+
+const routes = [
+  {
+    path: '/',
+    name: 'Home',
+    component: () => import('@/views/Home.vue'),  // Lazy loaded
+    meta: { requiresAuth: false }
+  },
+  {
+    path: '/dashboard',
+    name: 'Dashboard',
+    component: () => import('@/views/Dashboard.vue'),
+    meta: { requiresAuth: true },
+    children: [
+      {
+        path: 'settings',
+        name: 'Settings',
+        component: () => import('@/views/Settings.vue')
+      }
+    ]
+  },
+  {
+    path: '/users/:id',
+    name: 'UserProfile',
+    component: () => import('@/views/UserProfile.vue'),
+    props: true  // Pass params as props
+  },
+  {
+    path: '/:pathMatch(.*)*',
+    name: 'NotFound',
+    component: () => import('@/views/NotFound.vue')
+  }
+]
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes,
+  scrollBehavior(to, from, savedPosition) {
+    return savedPosition || { top: 0 }
+  }
+})
+
+// Global navigation guard
+router.beforeEach((to, from) => {
+  if (to.meta.requiresAuth && !isAuthenticated()) {
+    return { name: 'Login', query: { redirect: to.fullPath } }
+  }
+})
+
+export default router
+```
+
+```javascript
+// main.js
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+
+createApp(App)
+  .use(router)
+  .mount('#app')
+```
+
+```vue
+<!-- App.vue -->
+<template>
+  <nav>
+    <router-link to="/">Home</router-link>
+    <router-link to="/dashboard">Dashboard</router-link>
+  </nav>
+
+  <router-view v-slot="{ Component }">
+    <transition name="fade" mode="out-in">
+      <component :is="Component" />
+    </transition>
+  </router-view>
+</template>
+```
+
+## Modern Vue Router Features (2025+)
+
+```javascript
+// Data Loading API (Vue Router 4.2+)
+const routes = [
+  {
+    path: '/users/:id',
+    component: UserProfile,
+    // Load data at route level
+    loader: async (route) => {
+      return { user: await fetchUser(route.params.id) }
+    }
+  }
+]
+
+// View Transitions API integration
+const router = createRouter({
+  // Enable native browser view transitions
+  // Requires browser support (Chrome 111+)
+})
+```
+
+## Key Points
+
+1. **Use Vue Router for any app beyond a prototype** - The features are essential
+2. **Simple routing is for learning** - Understand the concepts, then use the library
+3. **Lazy loading is critical for bundle size** - Vue Router makes it trivial
+4. **Navigation guards prevent security issues** - Hard to get right manually
+5. **History mode requires Vue Router** - Clean URLs need proper handling
+6. **New features keep coming** - Data Loading API, View Transitions
+
+## Reference
+- [Vue.js Routing Guide](https://vuejs.org/guide/scaling-up/routing.html)
+- [Vue Router Documentation](https://router.vuejs.org/)
+- [Vue Router Getting Started](https://router.vuejs.org/guide/)

package/skills/vue-testing-best-practices/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hyf0, SerKo <https://github.com/serkodev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/vue-testing-best-practices/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: vue-testing-best-practices
+version: 1.0.0
+license: MIT
+author: github.com/vuejs-ai
+description: Use for Vue.js testing. Covers Vitest, Vue Test Utils, component testing, mocking, testing patterns, and Playwright for E2E testing.
+---
+
+Vue.js testing best practices, patterns, and common gotchas.
+
+### Testing
+- Setting up test infrastructure for Vue 3 projects → See [testing-vitest-recommended-for-vue](reference/testing-vitest-recommended-for-vue.md)
+- Tests keep breaking when refactoring component internals → See [testing-component-blackbox-approach](reference/testing-component-blackbox-approach.md)
+- Tests fail intermittently with race conditions → See [testing-async-await-flushpromises](reference/testing-async-await-flushpromises.md)
+- Composables using lifecycle hooks or inject fail to test → See [testing-composables-helper-wrapper](reference/testing-composables-helper-wrapper.md)
+- Getting "injection Symbol(pinia) not found" errors in tests → See [testing-pinia-store-setup](reference/testing-pinia-store-setup.md)
+- Components with async setup won't render in tests → See [testing-suspense-async-components](reference/testing-suspense-async-components.md)
+- Snapshot tests keep passing despite broken functionality → See [testing-no-snapshot-only](reference/testing-no-snapshot-only.md)
+- Choosing end-to-end testing framework for Vue apps → See [testing-e2e-playwright-recommended](reference/testing-e2e-playwright-recommended.md)
+- Tests need to verify computed styles or real DOM events → See [testing-browser-vs-node-runners](reference/testing-browser-vs-node-runners.md)
+- Testing components created with defineAsyncComponent fails → See [async-component-testing](reference/async-component-testing.md)
+- Teleported modal content can't be found in wrapper queries → See [teleport-testing-complexity](reference/teleport-testing-complexity.md)
+
+## Reference
+
+- [Vue.js Testing Guide](https://vuejs.org/guide/scaling-up/testing)
+- [Vue Test Utils](https://test-utils.vuejs.org/)
+- [Vitest Documentation](https://vitest.dev/)
+- [Playwright Documentation](https://playwright.dev/)

package/skills/vue-testing-best-practices/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/vuejs-ai/skills/vue-testing-best-practices`
+- **Git SHA:** `f3dd1bf4d3ac78331bdc903e4519d561c538ca6a`
+- **Synced:** 2026-03-24

package/skills/vue-testing-best-practices/reference/async-component-testing.md

@@ -0,0 +1,163 @@
+---
+title: Use flushPromises for Testing Async Components
+impact: HIGH
+impactDescription: Without awaiting async operations, tests make assertions before the component has rendered, causing false negatives
+type: gotcha
+tags: [vue3, testing, async, defineAsyncComponent, flushPromises, vitest]
+---
+
+# Use flushPromises for Testing Async Components
+
+**Impact: HIGH** - When testing async components created with `defineAsyncComponent`, you must use `await flushPromises()` to ensure the component has loaded before making assertions. Vue updates asynchronously, so tests that don't account for this will make assertions before the component has rendered.
+
+## Task Checklist
+
+- [ ] Use `async/await` in test functions for async components
+- [ ] Call `await flushPromises()` after mounting async components
+- [ ] Test loading states by making assertions before `flushPromises()`
+- [ ] Test error states using rejected promises in `defineAsyncComponent`
+- [ ] Use `trigger()` with `await` as it returns a Promise
+
+**Incorrect:**
+
+```javascript
+import { mount } from '@vue/test-utils'
+import { defineAsyncComponent } from 'vue'
+
+const AsyncWidget = defineAsyncComponent(() =>
+  import('./Widget.vue')
+)
+
+test('renders async component', () => {
+  const wrapper = mount(AsyncWidget)
+
+  // FAILS: Component hasn't loaded yet
+  expect(wrapper.text()).toContain('Widget Content')
+})
+```
+
+**Correct:**
+
+```javascript
+import { mount, flushPromises } from '@vue/test-utils'
+import { defineAsyncComponent, nextTick } from 'vue'
+
+const AsyncWidget = defineAsyncComponent(() =>
+  import('./Widget.vue')
+)
+
+test('renders async component', async () => {
+  const wrapper = mount(AsyncWidget)
+
+  // Wait for async component to load
+  await flushPromises()
+
+  expect(wrapper.text()).toContain('Widget Content')
+})
+
+test('shows loading state initially', async () => {
+  const AsyncWithLoading = defineAsyncComponent({
+    loader: () => import('./Widget.vue'),
+    loadingComponent: { template: '<div>Loading...</div>' },
+    delay: 0
+  })
+
+  const wrapper = mount(AsyncWithLoading)
+
+  // Check loading state immediately
+  expect(wrapper.text()).toContain('Loading...')
+
+  // Wait for component to load
+  await flushPromises()
+
+  // Check final state
+  expect(wrapper.text()).toContain('Widget Content')
+})
+```
+
+## Testing with Suspense
+
+```javascript
+import { mount, flushPromises } from '@vue/test-utils'
+import { Suspense, defineAsyncComponent, h } from 'vue'
+
+const AsyncWidget = defineAsyncComponent(() =>
+  import('./Widget.vue')
+)
+
+test('renders async component with Suspense', async () => {
+  const wrapper = mount({
+    components: { AsyncWidget },
+    template: `
+      <Suspense>
+        <AsyncWidget />
+        <template #fallback>
+          <div>Loading...</div>
+        </template>
+      </Suspense>
+    `
+  })
+
+  // Initially shows fallback
+  expect(wrapper.text()).toContain('Loading...')
+
+  // Wait for async resolution
+  await flushPromises()
+
+  // Now shows actual content
+  expect(wrapper.text()).toContain('Widget Content')
+})
+```
+
+## Testing Error States
+
+```javascript
+import { mount, flushPromises } from '@vue/test-utils'
+import { defineAsyncComponent } from 'vue'
+
+test('shows error component on load failure', async () => {
+  const AsyncWithError = defineAsyncComponent({
+    loader: () => Promise.reject(new Error('Failed to load')),
+    errorComponent: { template: '<div>Error loading component</div>' }
+  })
+
+  const wrapper = mount(AsyncWithError)
+
+  await flushPromises()
+
+  expect(wrapper.text()).toContain('Error loading component')
+})
+```
+
+## Utilities Reference
+
+| Utility | Purpose |
+|---------|---------|
+| `await flushPromises()` | Resolves all pending promises |
+| `await nextTick()` | Waits for Vue's next DOM update cycle |
+| `await wrapper.trigger('click')` | Triggers event and waits for update |
+
+## Dynamic Import Handling
+
+**Note:** Dynamic imports (`import('./File.vue')`) may require additional handling beyond `flushPromises()` in test environments. Test runners like Vitest handle module resolution differently than runtime bundlers, which can cause timing issues with dynamic imports. If `flushPromises()` alone doesn't resolve the component, consider:
+
+- Mocking the dynamic import to return the component synchronously
+- Using multiple `await flushPromises()` calls in sequence
+- Wrapping assertions in `waitFor()` or retry utilities
+- Configuring your test runner's module resolution settings
+
+```javascript
+// If flushPromises() isn't sufficient, mock the import
+vi.mock('./Widget.vue', () => ({
+  default: { template: '<div>Widget Content</div>' }
+}))
+
+// Or use multiple flush calls for nested async operations
+await flushPromises()
+await flushPromises()
+```
+
+## References
+
+- [Vue Test Utils - Asynchronous Behavior](https://test-utils.vuejs.org/guide/advanced/async-suspense)
+- [Vue.js Async Components Documentation](https://vuejs.org/guide/components/async)