@blueking/bkui-knowledge 0.0.1-beta.1 → 0.0.1-beta.11

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/hmr-vue-ssr.md

@@ -0,0 +1,124 @@
+---
+title: HMR Debugging for Vue SSR
+impact: MEDIUM
+impactDescription: fixes Hot Module Replacement breaking in Vue SSR applications
+type: efficiency
+tags: vite, hmr, ssr, vue, hot-reload, server-side-rendering
+---
+
+# HMR Debugging for Vue SSR
+
+**Impact: MEDIUM** - fixes Hot Module Replacement breaking in Vue SSR applications
+
+Hot Module Replacement breaks when modifying Vue component `<script setup>` sections in SSR applications. Changes cause errors instead of smooth updates, requiring full page reloads.
+
+## Symptoms
+
+- HMR works for `<template>` changes but breaks for `<script setup>`
+- "Cannot read property of undefined" after saving
+- Full page reload required after script changes
+- HMR works in dev:client but not dev:ssr
+
+## Root Cause
+
+SSR mode has a different transformation pipeline. The Vue plugin's HMR boundary detection doesn't handle SSR modules the same way as client modules.
+
+## Fix
+
+**Step 1: Ensure correct SSR plugin configuration**
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  ssr: {
+    // Don't externalize these for HMR to work
+    noExternal: ['vue', '@vue/runtime-core', '@vue/runtime-dom']
+  }
+})
+```
+
+**Step 2: Configure dev server for SSR HMR**
+```typescript
+// server.ts
+import { createServer } from 'vite'
+
+const vite = await createServer({
+  server: { middlewareMode: true },
+  appType: 'custom'
+})
+
+// Use vite.ssrLoadModule for server-side imports
+const { render } = await vite.ssrLoadModule('/src/entry-server.ts')
+
+// Handle HMR
+vite.watcher.on('change', async (file) => {
+  if (file.endsWith('.vue')) {
+    // Invalidate the module
+    const mod = vite.moduleGraph.getModuleById(file)
+    if (mod) {
+      vite.moduleGraph.invalidateModule(mod)
+    }
+  }
+})
+```
+
+**Step 3: Add HMR acceptance in entry-server**
+```typescript
+// entry-server.ts
+import { createApp } from './main'
+
+export async function render(url: string) {
+  const app = createApp()
+  // ... render logic
+}
+
+// Accept HMR updates
+if (import.meta.hot) {
+  import.meta.hot.accept()
+}
+```
+
+## Framework-Specific Solutions
+
+### Nuxt 3
+HMR should work out of the box. If not:
+```bash
+rm -rf .nuxt node_modules/.vite
+npm install
+npm run dev
+```
+
+### Vite SSR Template
+Ensure you're using the latest `@vitejs/plugin-vue`:
+```bash
+npm install @vitejs/plugin-vue@latest
+```
+
+## Debugging
+
+Enable verbose HMR logging:
+```typescript
+// vite.config.ts
+export default defineConfig({
+  server: {
+    hmr: {
+      overlay: true
+    }
+  },
+  logLevel: 'info'  // Shows HMR updates
+})
+```
+
+## Known Limitations
+
+- HMR for `<script>` (not `<script setup>`) may require full reload
+- SSR components with external dependencies may not hot-reload
+- State is not preserved for SSR components (expected behavior)
+
+## Reference
+
+- [vite-plugin-vue#525](https://github.com/vitejs/vite-plugin-vue/issues/525)
+- [Vite SSR Guide](https://vite.dev/guide/ssr.html)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/module-resolution-bundler.md

@@ -0,0 +1,81 @@
+---
+title: moduleResolution Bundler Migration Issues
+impact: HIGH
+impactDescription: fixes "Cannot find module" errors after @vue/tsconfig upgrade
+type: capability
+tags: moduleResolution, bundler, tsconfig, vue-tsconfig, node, esm
+---
+
+# moduleResolution Bundler Migration Issues
+
+**Impact: HIGH** - fixes "Cannot find module" errors after @vue/tsconfig upgrade
+
+Recent versions of `@vue/tsconfig` changed `moduleResolution` from `"node"` to `"bundler"`. This can break existing projects with errors like "Cannot find module 'vue'" or issues with `resolveJsonModule`.
+
+## Symptoms
+
+- `Cannot find module 'vue'` or other packages
+- `Option '--resolveJsonModule' cannot be specified without 'node' module resolution`
+- Errors appear after updating `@vue/tsconfig`
+- Some third-party packages no longer resolve
+
+## Root Cause
+
+`moduleResolution: "bundler"` requires:
+1. TypeScript 5.0+
+2. Packages to have proper `exports` field in package.json
+3. Different resolution rules than Node.js classic resolution
+
+## Fix
+
+**Option 1: Ensure TypeScript 5.0+ everywhere**
+```bash
+npm install -D typescript@^5.0.0
+```
+
+In monorepos, ALL packages must use TypeScript 5.0+.
+
+**Option 2: Add compatibility workaround**
+```json
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolvePackageJsonExports": false
+  }
+}
+```
+
+Setting `resolvePackageJsonExports: false` restores compatibility with packages that don't have proper exports.
+
+**Option 3: Revert to Node resolution**
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node"
+  }
+}
+```
+
+## Which Packages Break?
+
+Packages break if they:
+- Lack `exports` field in package.json
+- Have incorrect `exports` configuration
+- Rely on Node.js-specific resolution behavior
+
+## Diagnosis
+
+```bash
+# Check which resolution is being used
+cat tsconfig.json | grep moduleResolution
+
+# Test if a specific module resolves
+npx tsc --traceResolution 2>&1 | grep "module-name"
+```
+
+## Reference
+
+- [vuejs/tsconfig#8](https://github.com/vuejs/tsconfig/issues/8)
+- [TypeScript moduleResolution docs](https://www.typescriptlang.org/tsconfig#moduleResolution)
+- [Vite discussion#14001](https://github.com/vitejs/vite/discussions/14001)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/pinia-store-mocking.md

@@ -0,0 +1,159 @@
+---
+title: Mocking Pinia Stores with Vitest
+impact: HIGH
+impactDescription: properly mocks Pinia stores in component tests
+type: efficiency
+tags: pinia, vitest, testing, mock, createTestingPinia, store
+---
+
+# Mocking Pinia Stores with Vitest
+
+**Impact: HIGH** - properly mocks Pinia stores in component tests
+
+Developers struggle to properly mock Pinia stores: `createTestingPinia` requires explicit `createSpy` configuration, and "injection Symbol(pinia) not found" errors occur without proper setup.
+
+> **Important (@pinia/testing 1.0+):** The `createSpy` option is **REQUIRED**, not optional. Omitting it throws an error: "You must configure the `createSpy` option."
+
+## Symptoms
+
+- "injection Symbol(pinia) not found" error
+- "You must configure the `createSpy` option" error
+- Actions not properly mocked
+- Store state not reset between tests
+
+## Fix
+
+**Pattern 1: Basic setup with createTestingPinia**
+```typescript
+import { mount } from '@vue/test-utils'
+import { createTestingPinia } from '@pinia/testing'
+import { vi } from 'vitest'
+import MyComponent from './MyComponent.vue'
+import { useCounterStore } from '@/stores/counter'
+
+test('component uses store', async () => {
+  const wrapper = mount(MyComponent, {
+    global: {
+      plugins: [
+        createTestingPinia({
+          createSpy: vi.fn,  // REQUIRED in @pinia/testing 1.0+
+          initialState: {
+            counter: { count: 10 }  // Set initial state
+          }
+        })
+      ]
+    }
+  })
+
+  // Get the store instance AFTER mounting
+  const store = useCounterStore()
+
+  // Actions are automatically stubbed
+  await wrapper.find('button').trigger('click')
+  expect(store.increment).toHaveBeenCalled()
+})
+```
+
+**Pattern 2: Customize action behavior**
+```typescript
+test('component handles async action', async () => {
+  const wrapper = mount(MyComponent, {
+    global: {
+      plugins: [
+        createTestingPinia({
+          createSpy: vi.fn,
+          stubActions: false  // Don't stub, use real actions
+        })
+      ]
+    }
+  })
+
+  const store = useCounterStore()
+
+  // Override specific action
+  store.fetchData = vi.fn().mockResolvedValue({ items: [] })
+
+  await wrapper.find('.load-button').trigger('click')
+  expect(store.fetchData).toHaveBeenCalled()
+})
+```
+
+**Pattern 3: Testing store directly**
+```typescript
+import { setActivePinia, createPinia } from 'pinia'
+import { useCounterStore } from '@/stores/counter'
+
+describe('Counter Store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  test('increments count', () => {
+    const store = useCounterStore()
+    expect(store.count).toBe(0)
+
+    store.increment()
+    expect(store.count).toBe(1)
+  })
+})
+```
+
+## Setup Store with Vitest
+
+```typescript
+// stores/counter.ts - Setup store syntax
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0)
+  const doubleCount = computed(() => count.value * 2)
+
+  function increment() {
+    count.value++
+  }
+
+  return { count, doubleCount, increment }
+})
+
+// Test file
+test('setup store works', async () => {
+  const pinia = createTestingPinia({
+    createSpy: vi.fn,
+    initialState: {
+      counter: { count: 5 }
+    }
+  })
+
+  const wrapper = mount(MyComponent, {
+    global: { plugins: [pinia] }
+  })
+
+  const store = useCounterStore()
+  expect(store.count).toBe(5)
+  expect(store.doubleCount).toBe(10)
+})
+```
+
+## Reset Between Tests
+
+```typescript
+describe('Store Tests', () => {
+  let pinia: Pinia
+
+  beforeEach(() => {
+    pinia = createTestingPinia({
+      createSpy: vi.fn
+    })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('test 1', () => { /* ... */ })
+  test('test 2', () => { /* ... */ })
+})
+```
+
+## Reference
+
+- [Pinia Testing Guide](https://pinia.vuejs.org/cookbook/testing.html)
+- [Pinia Discussion #2092](https://github.com/vuejs/pinia/discussions/2092)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/script-setup-jsdoc.md

@@ -0,0 +1,85 @@
+---
+title: JSDoc Documentation for Script Setup Components
+impact: MEDIUM
+impactDescription: enables proper documentation for composition API components
+type: capability
+tags: jsdoc, script-setup, documentation, composition-api, component
+---
+
+# JSDoc Documentation for Script Setup Components
+
+**Impact: MEDIUM** - enables proper documentation for composition API components
+
+`<script setup>` doesn't have an obvious place to attach JSDoc comments for the component itself. Use a dual-script pattern.
+
+## Problem
+
+**Incorrect:**
+```vue
+<script setup lang="ts">
+/**
+ * This comment doesn't appear in IDE hover or docs
+ * @component
+ */
+import { ref } from 'vue'
+
+const count = ref(0)
+</script>
+```
+
+JSDoc comments inside `<script setup>` don't attach to the component export because there's no explicit export statement.
+
+## Solution
+
+Use both `<script>` and `<script setup>` blocks:
+
+**Correct:**
+```vue
+<script lang="ts">
+/**
+ * A counter component that displays and increments a value.
+ *
+ * @example
+ * ```vue
+ * <Counter :initial="5" @update="handleUpdate" />
+ * ```
+ *
+ * @component
+ */
+export default {}
+</script>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const props = defineProps<{
+  /** Starting value for the counter */
+  initial?: number
+}>()
+
+const emit = defineEmits<{
+  /** Emitted when counter value changes */
+  update: [value: number]
+}>()
+
+const count = ref(props.initial ?? 0)
+</script>
+```
+
+## How It Works
+
+- The regular `<script>` block's default export is merged with `<script setup>`
+- JSDoc on `export default {}` attaches to the component
+- Props and emits JSDoc in `<script setup>` still work normally
+
+## What Gets Documented
+
+| Location | Shows In |
+|----------|----------|
+| `export default {}` JSDoc | Component import hover |
+| `defineProps` JSDoc | Prop hover in templates |
+| `defineEmits` JSDoc | Event handler hover |
+
+## Reference
+
+- [Vue Language Tools Discussion #5932](https://github.com/vuejs/language-tools/discussions/5932)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/strict-css-modules.md

@@ -0,0 +1,68 @@
+---
+title: Enable Strict CSS Modules Type Checking
+impact: MEDIUM
+impactDescription: catches typos in CSS module class names at compile time
+type: capability
+tags: strictCssModules, vueCompilerOptions, css-modules, style-module
+---
+
+# Enable Strict CSS Modules Type Checking
+
+**Impact: MEDIUM** - catches typos in CSS module class names at compile time
+
+When using CSS modules with `<style module>`, Vue doesn't validate class names by default. Enable `strictCssModules` to catch typos and undefined classes.
+
+## Problem
+
+CSS module class name errors go undetected:
+
+```vue
+<script setup lang="ts">
+// No error for typo in class name
+</script>
+
+<template>
+  <div :class="$style.buttn">Click me</div>
+</template>
+
+<style module>
+.button {
+  background: blue;
+}
+</style>
+```
+
+The typo `buttn` instead of `button` silently fails at runtime.
+
+## Solution
+
+Enable `strictCssModules` in your tsconfig:
+
+```json
+// tsconfig.json or tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "strictCssModules": true
+  }
+}
+```
+
+Now `$style.buttn` will show a type error because `buttn` doesn't exist in the CSS module.
+
+## What Gets Checked
+
+| Access | With strictCssModules |
+|--------|----------------------|
+| `$style.validClass` | OK |
+| `$style.typo` | Error: Property 'typo' does not exist |
+| `$style['dynamic']` | OK (dynamic access not checked) |
+
+## Limitations
+
+- Only checks static property access (`$style.className`)
+- Dynamic access (`$style[variable]`) is not validated
+- Only works with `<style module>`, not external CSS files
+
+## Reference
+
+- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/unplugin-auto-import-conflicts.md

@@ -0,0 +1,97 @@
+---
+title: unplugin-vue-components and unplugin-auto-import Type Conflicts
+impact: HIGH
+impactDescription: fixes component types resolving as any when using both plugins
+type: capability
+tags: unplugin-vue-components, unplugin-auto-import, types, any, dts
+---
+
+# unplugin-vue-components and unplugin-auto-import Type Conflicts
+
+**Impact: HIGH** - fixes component types resolving as any when using both plugins
+
+Installing both `unplugin-vue-components` and `unplugin-auto-import` can cause component types to resolve as `any`. The generated `.d.ts` files conflict with each other.
+
+## Symptoms
+
+- Components typed as `any` instead of proper component types
+- No autocomplete for component props
+- No type errors for invalid props
+- Types work when using only one plugin but break with both
+
+## Root Cause
+
+Both plugins generate declaration files (`components.d.ts` and `auto-imports.d.ts`) that can have conflicting declarations. TypeScript declaration merging fails silently.
+
+## Fix
+
+**Step 1: Ensure both .d.ts files are in tsconfig include**
+```json
+{
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.vue",
+    "components.d.ts",
+    "auto-imports.d.ts"
+  ]
+}
+```
+
+**Step 2: Set explicit, different dts paths**
+```typescript
+// vite.config.ts
+import Components from 'unplugin-vue-components/vite'
+import AutoImport from 'unplugin-auto-import/vite'
+
+export default defineConfig({
+  plugins: [
+    Components({
+      dts: 'src/types/components.d.ts'  // Explicit unique path
+    }),
+    AutoImport({
+      dts: 'src/types/auto-imports.d.ts'  // Explicit unique path
+    })
+  ]
+})
+```
+
+**Step 3: Regenerate type files**
+```bash
+# Delete existing .d.ts files
+rm components.d.ts auto-imports.d.ts
+
+# Restart dev server to regenerate
+npm run dev
+```
+
+**Step 4: Verify no duplicate declarations**
+
+Check that the same component isn't declared in both files.
+
+## Plugin Order Matters
+
+Configure Components plugin AFTER AutoImport:
+```typescript
+plugins: [
+  AutoImport({ /* ... */ }),
+  Components({ /* ... */ })  // Must come after AutoImport
+]
+```
+
+## Common Mistake: Duplicate Imports
+
+Don't configure the same import in both plugins:
+```typescript
+// Wrong - Vue imported in both
+AutoImport({
+  imports: ['vue']
+})
+Components({
+  resolvers: [/* includes Vue components */]
+})
+```
+
+## Reference
+
+- [unplugin-vue-components#640](https://github.com/unplugin/unplugin-vue-components/issues/640)
+- [unplugin-auto-import docs](https://github.com/unplugin/unplugin-auto-import)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/volar-3-breaking-changes.md

@@ -0,0 +1,66 @@
+---
+title: Volar 3.0 Breaking Changes
+impact: HIGH
+impactDescription: fixes editor integration after Volar/vue-language-server upgrade
+type: capability
+tags: volar, vue-language-server, neovim, vscode, ide, ts_ls, vtsls
+---
+
+# Volar 3.0 Breaking Changes
+
+**Impact: HIGH** - fixes editor integration after Volar/vue-language-server upgrade
+
+Volar 3.0 (vue-language-server 3.x) introduced breaking changes to the language server protocol. Editors configured for Volar 2.x will break with errors like "vue_ls doesn't work with ts_ls.. it expects vtsls".
+
+## Symptoms
+
+- `vue_ls doesn't work with ts_ls`
+- TypeScript features stop working in Vue files
+- No autocomplete, type hints, or error highlighting
+- Editor shows "Language server initialization failed"
+
+## Fix by Editor
+
+### VSCode
+
+Update the "Vue - Official" extension to latest version. It manages the language server automatically.
+
+### NeoVim (nvim-lspconfig)
+
+**Option 1: Use vtsls instead of ts_ls**
+```lua
+-- Replace ts_ls/tsserver with vtsls
+require('lspconfig').vtsls.setup({})
+require('lspconfig').volar.setup({})
+```
+
+**Option 2: Downgrade vue-language-server**
+```bash
+npm install -g @vue/language-server@2.1.10
+```
+
+### JetBrains IDEs
+
+Update to latest Vue plugin. If issues persist, disable and re-enable the Vue plugin.
+
+## What Changed in 3.0
+
+| Feature | Volar 2.x | Volar 3.0 |
+|---------|-----------|-----------|
+| Package name | volar | vue_ls |
+| TypeScript integration | ts_ls/tsserver | vtsls required |
+| Hybrid mode | Optional | Default |
+
+## Workaround: Stay on 2.x
+
+If upgrading is not possible:
+```bash
+npm install -g @vue/language-server@^2.0.0
+```
+
+Pin in your project's package.json to prevent accidental upgrades.
+
+## Reference
+
+- [vuejs/language-tools#5598](https://github.com/vuejs/language-tools/issues/5598)
+- [NeoVim Vue Setup Guide](https://dev.to/danwalsh/solved-vue-3-typescript-inlay-hint-support-in-neovim-53ej)