@biggora/claude-plugins 1.1.1 → 1.2.2

package/src/skills/vite-best-practices/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: vite-best-practices
+description: Vite build tool configuration, plugin API, SSR, library mode, and Vite 8 Rolldown/Oxc migration. Use when working with Vite projects, vite.config.ts, Vite plugins, building libraries or SSR apps with Vite, migrating from older Vite versions, or configuring Rolldown/Oxc options. Also use when the user mentions HMR, import.meta.glob, virtual modules, or Vite environment variables.
+---
+
+# Vite
+
+> Based on Vite 8.0 stable (March 2026). Vite 8 uses Rolldown bundler and Oxc transformer, replacing esbuild + Rollup.
+
+Vite is a next-generation frontend build tool with fast dev server (native ESM + HMR) and optimized production builds powered by Rolldown.
+
+## Key Vite 8 Changes
+
+Vite 8 replaces the dual esbuild+Rollup architecture with Rolldown (unified Rust-based bundler) and Oxc (transformer/minifier). A **compatibility layer** auto-converts old `esbuild` and `rollupOptions` configs, but both are deprecated — always use the new names in new code:
+
+| Deprecated (still works) | Replacement |
+|--------------------------|-------------|
+| `build.rollupOptions` | `build.rolldownOptions` |
+| `esbuild` | `oxc` |
+| `optimizeDeps.esbuildOptions` | `optimizeDeps.rolldownOptions` |
+| `build.minify: 'esbuild'` | `build.minify: 'oxc'` (default) |
+
+## Preferences
+
+- Use TypeScript: prefer `vite.config.ts`
+- Always use ESM — avoid CommonJS
+- Use `import.meta.dirname` (ESM) not `__dirname` (CJS) in config files
+- Use `rolldownOptions` not `rollupOptions` in new code
+- Use `oxc` not `esbuild` in new code
+
+## Core
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Configuration | `vite.config.ts`, `defineConfig`, conditional configs, `loadEnv`, new v8 options | [core-config](references/core-config.md) |
+| Features | `import.meta.glob`, asset queries, `import.meta.env`, HMR API, CSS modules | [core-features](references/core-features.md) |
+| Plugin API | Vite/Rolldown hooks, virtual modules, hook filters, plugin ordering | [core-plugin-api](references/core-plugin-api.md) |
+
+## Build & SSR
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Build & SSR | Library mode, SSR middleware, `ssrLoadModule`, multi-page apps, JavaScript API | [build-and-ssr](references/build-and-ssr.md) |
+
+## Advanced
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Environment API | Vite 6+ multi-environment support, custom runtimes | [environment-api](references/environment-api.md) |
+| Rolldown Migration | Vite 8 migration: complete esbuild→oxc and rollupOptions→rolldownOptions mapping, breaking changes | [rolldown-migration](references/rolldown-migration.md) |
+
+## Quick Reference
+
+### CLI Commands
+
+```bash
+vite              # Start dev server
+vite build        # Production build
+vite preview      # Preview production build
+vite build --ssr  # SSR build
+```
+
+### Common Config (Vite 8)
+
+```ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [],
+  resolve: {
+    alias: { '@': '/src' },
+    tsconfigPaths: true,  // New in v8: auto-resolve TS path aliases
+  },
+  server: {
+    port: 3000,
+    proxy: { '/api': 'http://localhost:8080' },
+    forwardConsole: true,  // New in v8: browser logs → terminal
+  },
+  build: {
+    target: 'esnext',
+    outDir: 'dist',
+    rolldownOptions: {},   // NOT rollupOptions
+  },
+  oxc: {                   // NOT esbuild
+    jsx: {
+      runtime: 'automatic',
+      importSource: 'react',
+    },
+  },
+})
+```
+
+### Official Plugins
+
+- `@vitejs/plugin-react` v6 — React with Oxc transforms (Babel removed)
+- `@vitejs/plugin-react-swc` — React with SWC
+- `@vitejs/plugin-vue` — Vue 3 SFC support
+- `@vitejs/plugin-vue-jsx` — Vue 3 JSX
+- `@vitejs/plugin-legacy` — Legacy browser support
+
+### Oxc JSX Quick Reference
+
+```ts
+// React (automatic runtime — default)
+oxc: { jsx: { runtime: 'automatic', importSource: 'react' } }
+
+// Preact (automatic)
+oxc: { jsx: { runtime: 'automatic', importSource: 'preact' } }
+
+// Preact (classic with h/Fragment)
+oxc: { jsx: { runtime: 'classic', pragma: 'h', pragmaFrag: 'Fragment' } }
+
+// Auto-inject React import (legacy patterns)
+oxc: { jsxInject: `import React from 'react'` }
+```

package/src/skills/vite-best-practices/references/build-and-ssr.md

@@ -0,0 +1,255 @@
+---
+name: vite-build-ssr
+description: Vite 8 library mode and SSR configuration
+---
+
+# Build and SSR
+
+## Library Mode
+
+Build a library for distribution:
+
+```ts
+// vite.config.ts
+import { resolve } from 'node:path'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(import.meta.dirname, 'lib/main.ts'),
+      name: 'MyLib',
+      fileName: 'my-lib',
+    },
+    rolldownOptions: {
+      external: ['vue', 'react'],
+      output: {
+        globals: {
+          vue: 'Vue',
+          react: 'React',
+        },
+      },
+    },
+  },
+})
+```
+
+**Note:** Use `import.meta.dirname` (ESM) not `__dirname` (CJS).
+
+### Multiple Entries
+
+```ts
+build: {
+  lib: {
+    entry: {
+      'my-lib': resolve(import.meta.dirname, 'lib/main.ts'),
+      secondary: resolve(import.meta.dirname, 'lib/secondary.ts'),
+    },
+    name: 'MyLib',
+  },
+}
+```
+
+### Output Formats
+
+- Single entry: `es` and `umd`
+- Multiple entries: `es` and `cjs`
+
+### Package.json Setup
+
+```json
+{
+  "name": "my-lib",
+  "type": "module",
+  "files": ["dist"],
+  "main": "./dist/my-lib.umd.cjs",
+  "module": "./dist/my-lib.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/my-lib.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/my-lib.umd.cjs"
+      }
+    },
+    "./style.css": "./dist/my-lib.css"
+  }
+}
+```
+
+**Tip:** List `types` first in each export condition — Node.js resolves conditions top-to-bottom.
+
+## Multi-Page App
+
+```ts
+export default defineConfig({
+  build: {
+    rolldownOptions: {
+      input: {
+        main: resolve(import.meta.dirname, 'index.html'),
+        nested: resolve(import.meta.dirname, 'nested/index.html'),
+      },
+    },
+  },
+})
+```
+
+## Chunk Splitting (Vite 8)
+
+The `manualChunks` object form is removed in Vite 8. The function form is deprecated — use `codeSplitting` instead for advanced chunk control.
+
+## SSR Development
+
+### Middleware Mode
+
+Use Vite as middleware in a custom server:
+
+```ts
+import express from 'express'
+import { createServer as createViteServer } from 'vite'
+
+const app = express()
+
+const vite = await createViteServer({
+  server: { middlewareMode: true },
+  appType: 'custom',
+})
+
+app.use(vite.middlewares)
+
+app.use('*all', async (req, res, next) => {
+  const url = req.originalUrl
+
+  // 1. Read and transform index.html
+  let template = await fs.readFile('index.html', 'utf-8')
+  template = await vite.transformIndexHtml(url, template)
+
+  // 2. Load server entry
+  const { render } = await vite.ssrLoadModule('/src/entry-server.ts')
+
+  // 3. Render app
+  const appHtml = await render(url)
+
+  // 4. Inject into template
+  const html = template.replace('<!--ssr-outlet-->', appHtml)
+
+  res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
+})
+
+app.listen(5173)
+```
+
+### SSR Build
+
+```json
+{
+  "scripts": {
+    "build:client": "vite build --outDir dist/client",
+    "build:server": "vite build --outDir dist/server --ssr src/entry-server.ts"
+  }
+}
+```
+
+The `--ssr` flag:
+- Externalizes dependencies by default
+- Outputs for Node.js consumption
+
+### SSR Manifest
+
+Generate asset mapping for preload hints:
+
+```bash
+vite build --outDir dist/client --ssrManifest
+```
+
+Creates `dist/client/.vite/ssr-manifest.json` mapping module IDs to chunks.
+
+### SSR Externals
+
+Control which deps get bundled vs externalized:
+
+```ts
+export default defineConfig({
+  ssr: {
+    noExternal: ['some-package'],  // Bundle this dep
+    external: ['another-package'], // Externalize this dep
+  },
+})
+```
+
+### Conditional Logic
+
+```ts
+if (import.meta.env.SSR) {
+  // Server-only code (tree-shaken from client)
+}
+```
+
+## JavaScript API
+
+### createServer
+
+```ts
+import { createServer } from 'vite'
+
+const server = await createServer({
+  configFile: false,
+  root: import.meta.dirname,
+  server: { port: 1337 },
+})
+
+await server.listen()
+server.printUrls()
+```
+
+### build
+
+```ts
+import { build } from 'vite'
+
+await build({
+  root: './project',
+  build: { outDir: 'dist' },
+})
+```
+
+**Vite 8:** `build()` throws `BundleError` (not raw error) with `.errors?: RolldownError[]` array.
+
+### preview
+
+```ts
+import { preview } from 'vite'
+
+const previewServer = await preview({
+  preview: { port: 8080, open: true },
+})
+previewServer.printUrls()
+```
+
+### resolveConfig
+
+```ts
+import { resolveConfig } from 'vite'
+
+const config = await resolveConfig({}, 'build')
+```
+
+### loadEnv
+
+```ts
+import { loadEnv } from 'vite'
+
+const env = loadEnv('development', process.cwd(), '')
+// Loads all env vars (empty prefix = no filtering)
+```
+
+<!--
+Source references:
+- https://vite.dev/guide/build
+- https://vite.dev/guide/ssr
+- https://vite.dev/guide/api-javascript
+- https://vite.dev/guide/migration
+-->

package/src/skills/vite-best-practices/references/core-config.md

@@ -0,0 +1,231 @@
+---
+name: vite-config
+description: Vite 8 configuration patterns using vite.config.ts
+---
+
+# Vite Configuration
+
+## Basic Setup
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  // config options
+})
+```
+
+Vite auto-resolves `vite.config.ts` from project root. Supports ES modules syntax regardless of `package.json` type.
+
+## Conditional Config
+
+Export a function to access command and mode:
+
+```ts
+export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
+  if (command === 'serve') {
+    return { /* dev config */ }
+  } else {
+    return { /* build config */ }
+  }
+})
+```
+
+- `command`: `'serve'` during dev, `'build'` for production
+- `mode`: `'development'` or `'production'` (or custom via `--mode`)
+
+## Async Config
+
+```ts
+export default defineConfig(async ({ command, mode }) => {
+  const data = await fetchSomething()
+  return { /* config */ }
+})
+```
+
+## Using Environment Variables in Config
+
+`.env` files are loaded **after** config resolution. Use `loadEnv` to access them in config:
+
+```ts
+import { defineConfig, loadEnv } from 'vite'
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '')
+
+  return {
+    define: {
+      __APP_ENV__: JSON.stringify(env.APP_ENV),
+    },
+    server: {
+      port: env.APP_PORT ? Number(env.APP_PORT) : 5173,
+    },
+  }
+})
+```
+
+## Key Config Options
+
+### resolve.alias
+
+```ts
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': '/src',
+      '~': '/src',
+    },
+  },
+})
+```
+
+### resolve.tsconfigPaths (Vite 8)
+
+Auto-resolve TypeScript path aliases from `tsconfig.json`:
+
+```ts
+export default defineConfig({
+  resolve: {
+    tsconfigPaths: true,  // default: false (small perf cost)
+  },
+})
+```
+
+### define (Global Constants)
+
+```ts
+export default defineConfig({
+  define: {
+    __APP_VERSION__: JSON.stringify('1.0.0'),
+    __API_URL__: 'window.__backend_api_url',
+  },
+})
+```
+
+Values must be JSON-serializable or single identifiers. Non-strings auto-wrapped with `JSON.stringify`.
+
+### plugins
+
+```ts
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+})
+```
+
+Plugins array is flattened; falsy values ignored.
+
+### oxc (Vite 8 — replaces esbuild)
+
+```ts
+export default defineConfig({
+  oxc: {
+    jsx: {
+      runtime: 'automatic',  // or 'classic'
+      importSource: 'react',
+    },
+    jsxInject: `import React from 'react'`,  // auto-inject
+    include: ['**/*.ts', '**/*.tsx'],         // default: ts, jsx, tsx
+    exclude: ['node_modules/**'],
+  },
+})
+```
+
+Set `oxc: false` to disable Oxc transformation entirely.
+
+**Note:** The old `esbuild` option still works via compatibility layer but is deprecated. Always use `oxc` in new code.
+
+### server.proxy
+
+```ts
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3000',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ''),
+      },
+    },
+  },
+})
+```
+
+### server.forwardConsole (Vite 8)
+
+Route browser console logs to the dev server terminal:
+
+```ts
+export default defineConfig({
+  server: {
+    forwardConsole: true,  // useful for AI coding agents detecting runtime errors
+  },
+})
+```
+
+### devtools (Vite 8 — Experimental)
+
+```ts
+export default defineConfig({
+  devtools: true,  // requires @vitejs/devtools installed; build mode only
+})
+```
+
+### build.target
+
+Default: Baseline Widely Available browsers (Chrome 111+, Firefox 114+, Safari 16.4+).
+
+```ts
+export default defineConfig({
+  build: {
+    target: 'esnext', // or 'es2020', ['chrome90', 'firefox88']
+  },
+})
+```
+
+### build.rolldownOptions (Vite 8 — replaces rollupOptions)
+
+```ts
+export default defineConfig({
+  build: {
+    rolldownOptions: {
+      external: ['vue'],
+      output: {
+        globals: { vue: 'Vue' },
+      },
+    },
+  },
+})
+```
+
+**Note:** `build.rollupOptions` still works via compat layer but is deprecated.
+
+## TypeScript Intellisense
+
+For plain JS config files:
+
+```js
+/** @type {import('vite').UserConfig} */
+export default {
+  // ...
+}
+```
+
+Or use `satisfies`:
+
+```ts
+import type { UserConfig } from 'vite'
+
+export default {
+  // ...
+} satisfies UserConfig
+```
+
+<!--
+Source references:
+- https://vite.dev/config/
+- https://vite.dev/guide/
+- https://vite.dev/guide/migration
+-->