@biggora/claude-plugins 1.2.0 → 1.3.0

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

@@ -0,0 +1,294 @@
+---
+name: vite-plugin-api
+description: Vite plugin authoring with Rolldown hooks and Vite-specific hooks (Vite 8)
+---
+
+# Vite Plugin API
+
+Vite plugins extend Rolldown's plugin interface with Vite-specific hooks. Refer to Rolldown's plugin documentation for the base API.
+
+## Basic Structure
+
+```ts
+import type { Plugin } from 'vite'
+
+function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',
+    // hooks...
+  }
+}
+```
+
+## Vite-Specific Hooks
+
+### config
+
+Modify config before resolution:
+
+```ts
+const plugin = () => ({
+  name: 'add-alias',
+  config: () => ({
+    resolve: {
+      alias: { foo: 'bar' },
+    },
+  }),
+})
+```
+
+### configResolved
+
+Access final resolved config:
+
+```ts
+const plugin = () => {
+  let config: ResolvedConfig
+  return {
+    name: 'read-config',
+    configResolved(resolvedConfig) {
+      config = resolvedConfig
+    },
+    transform(code, id) {
+      if (config.command === 'serve') { /* dev */ }
+    },
+  }
+}
+```
+
+### configureServer
+
+Add custom middleware to dev server:
+
+```ts
+const plugin = () => ({
+  name: 'custom-middleware',
+  configureServer(server) {
+    server.middlewares.use((req, res, next) => {
+      // handle request
+      next()
+    })
+  },
+})
+```
+
+Return function to run **after** internal middlewares:
+
+```ts
+configureServer(server) {
+  return () => {
+    server.middlewares.use((req, res, next) => {
+      // runs after Vite's middlewares
+    })
+  }
+}
+```
+
+### transformIndexHtml
+
+Transform HTML entry files:
+
+```ts
+const plugin = () => ({
+  name: 'html-transform',
+  transformIndexHtml(html) {
+    return html.replace(/<title>(.*?)<\/title>/, '<title>New Title</title>')
+  },
+})
+```
+
+Inject tags:
+
+```ts
+transformIndexHtml() {
+  return [
+    { tag: 'script', attrs: { src: '/inject.js' }, injectTo: 'body' },
+  ]
+}
+```
+
+### handleHotUpdate
+
+Custom HMR handling:
+
+```ts
+handleHotUpdate({ server, modules, timestamp }) {
+  server.ws.send({ type: 'custom', event: 'special-update', data: {} })
+  return [] // empty = skip default HMR
+}
+```
+
+## Virtual Modules
+
+Serve virtual content without files on disk:
+
+```ts
+import { exactRegex } from '@rolldown/pluginutils'
+
+const plugin = () => {
+  const virtualModuleId = 'virtual:my-module'
+  const resolvedId = '\0' + virtualModuleId
+
+  return {
+    name: 'virtual-module',
+    resolveId: {
+      filter: { id: exactRegex(virtualModuleId) },
+      handler() {
+        return resolvedId
+      },
+    },
+    load: {
+      filter: { id: exactRegex(resolvedId) },
+      handler() {
+        return `export const msg = "from virtual module"`
+      },
+    },
+  }
+}
+```
+
+Usage:
+
+```ts
+import { msg } from 'virtual:my-module'
+```
+
+Convention: prefix user-facing path with `virtual:`, prefix resolved id with `\0`.
+
+**Note:** The older function-based syntax (`resolveId(id) { ... }`) still works — the filter-based syntax above is the newer, more performant pattern from Rolldown.
+
+## Hook Filters (Vite 8 / Rolldown)
+
+Hook filters reduce overhead by letting plugins declare which files they care about, so hooks are only called when relevant:
+
+```ts
+{
+  name: 'transform-ts',
+  transform: {
+    filter: { id: /\.(ts|tsx)$/ },
+    handler(code, id) {
+      // Only called for .ts/.tsx files
+      return { code: transform(code), map: null }
+    },
+  },
+}
+```
+
+## moduleType in load/transform (Vite 8)
+
+When converting non-JS content to JavaScript, you must specify `moduleType: 'js'` so Rolldown interprets the output correctly:
+
+```ts
+{
+  name: 'txt-loader',
+  load(id) {
+    if (id.endsWith('.txt')) {
+      const content = fs.readFileSync(id, 'utf-8')
+      return {
+        code: `export default ${JSON.stringify(content)}`,
+        moduleType: 'js',
+      }
+    }
+  },
+}
+```
+
+## Plugin Ordering
+
+Use `enforce` to control execution order:
+
+```ts
+{
+  name: 'pre-plugin',
+  enforce: 'pre',  // runs before core plugins
+}
+
+{
+  name: 'post-plugin',
+  enforce: 'post', // runs after build plugins
+}
+```
+
+Order: Alias → `enforce: 'pre'` → Core → User (no enforce) → Build → `enforce: 'post'` → Post-build
+
+## Conditional Application
+
+```ts
+{
+  name: 'build-only',
+  apply: 'build',  // or 'serve'
+}
+
+// Function form:
+{
+  apply(config, { command }) {
+    return command === 'build' && !config.build.ssr
+  }
+}
+```
+
+## Universal Hooks (from Rolldown)
+
+These work in both dev and build:
+
+- `resolveId(id, importer)` — Resolve import paths
+- `load(id)` — Load module content
+- `transform(code, id)` — Transform module code
+
+```ts
+transform(code, id) {
+  if (id.endsWith('.custom')) {
+    return { code: compile(code), map: null }
+  }
+}
+```
+
+**Note:** `moduleParsed` hook is NOT called during dev in Vite 8.
+
+## Detecting Rolldown at Runtime
+
+```ts
+transform(code, id) {
+  if (this.meta.rolldownVersion) {
+    // Running on Rolldown-powered Vite (8+)
+  }
+}
+```
+
+## Client-Server Communication
+
+Server to client:
+
+```ts
+configureServer(server) {
+  server.ws.send('my:event', { msg: 'hello' })
+}
+```
+
+Client side:
+
+```ts
+if (import.meta.hot) {
+  import.meta.hot.on('my:event', (data) => {
+    console.log(data.msg)
+  })
+}
+```
+
+Client to server:
+
+```ts
+// Client
+import.meta.hot.send('my:from-client', { msg: 'Hey!' })
+
+// Server
+server.ws.on('my:from-client', (data, client) => {
+  client.send('my:ack', { msg: 'Got it!' })
+})
+```
+
+<!--
+Source references:
+- https://vite.dev/guide/api-plugin
+- https://vite.dev/guide/migration
+-->

package/src/skills/vite-best-practices/references/environment-api.md

@@ -0,0 +1,108 @@
+---
+name: vite-environment-api
+description: Vite 6+ Environment API for multiple runtime environments
+---
+
+# Environment API (Vite 6+)
+
+The Environment API formalizes multiple runtime environments beyond the traditional client/SSR split.
+
+## Concept
+
+Before Vite 6: Two implicit environments (`client` and `ssr`).
+
+Vite 6+: Configure as many environments as needed (browser, node server, edge server, etc.).
+
+## Basic Configuration
+
+For SPA/MPA, nothing changes—options apply to the implicit `client` environment:
+
+```ts
+export default defineConfig({
+  build: { sourcemap: false },
+  optimizeDeps: { include: ['lib'] },
+})
+```
+
+## Multiple Environments
+
+```ts
+export default defineConfig({
+  build: { sourcemap: false },  // Inherited by all environments
+  optimizeDeps: { include: ['lib'] },  // Client only
+  environments: {
+    // SSR environment
+    server: {},
+    // Edge runtime environment
+    edge: {
+      resolve: { noExternal: true },
+    },
+  },
+})
+```
+
+Environments inherit top-level config. Some options (like `optimizeDeps`) only apply to `client` by default.
+
+## Environment Options
+
+```ts
+interface EnvironmentOptions {
+  define?: Record<string, any>
+  resolve?: EnvironmentResolveOptions
+  optimizeDeps: DepOptimizationOptions
+  consumer?: 'client' | 'server'
+  dev: DevOptions
+  build: BuildOptions
+}
+```
+
+## Custom Environment Instances
+
+Runtime providers can define custom environments:
+
+```ts
+import { customEnvironment } from 'vite-environment-provider'
+
+export default defineConfig({
+  environments: {
+    ssr: customEnvironment({
+      build: { outDir: '/dist/ssr' },
+    }),
+  },
+})
+```
+
+Example: Cloudflare's Vite plugin runs code in `workerd` runtime during development.
+
+## Backward Compatibility
+
+- `server.moduleGraph` returns mixed client/SSR view
+- `ssrLoadModule` still works
+- Existing SSR apps work unchanged
+
+## When to Use
+
+- **End users**: Usually don't need to configure—frameworks handle it
+- **Plugin authors**: Use for environment-aware transformations
+- **Framework authors**: Create custom environments for their runtime needs
+
+## Plugin Environment Access
+
+Plugins can access environment in hooks:
+
+```ts
+{
+  name: 'env-aware',
+  transform(code, id, options) {
+    if (options?.ssr) {
+      // SSR-specific transform
+    }
+  },
+}
+```
+
+<!--
+Source references:
+- https://vite.dev/guide/api-environment
+- https://vite.dev/blog/announcing-vite6
+-->

package/src/skills/vite-best-practices/references/rolldown-migration.md

@@ -0,0 +1,242 @@
+---
+name: vite-rolldown
+description: Vite 8 Rolldown bundler and Oxc transformer migration from Vite 7
+---
+
+# Rolldown Migration (Vite 8)
+
+Vite 8 (stable March 2026) replaces esbuild+Rollup with Rolldown, a unified Rust-based bundler. Performance gains of 10-30x for production builds are typical.
+
+## What Changed
+
+| Before (Vite 7) | After (Vite 8) | Compat Layer |
+|-----------------|----------------|--------------|
+| esbuild (dev transform) | Oxc Transformer | `esbuild` auto-converts to `oxc` |
+| esbuild (dep pre-bundling) | Rolldown | `esbuildOptions` auto-converts |
+| esbuild (JS minification) | Oxc Minifier | `minify: 'esbuild'` = fallback |
+| esbuild (CSS minification) | Lightning CSS | `cssMinify: 'esbuild'` = fallback |
+| Rollup (production build) | Rolldown | `rollupOptions` auto-converts |
+| `rollupOptions` | `rolldownOptions` | deprecated, auto-converts |
+| `esbuild` option | `oxc` option | deprecated, auto-converts |
+
+**Important:** A compatibility layer auto-converts old config names, so many projects upgrade with zero config changes. However, both `esbuild` and `rollupOptions` are deprecated and will be removed in a future version. Always use the new names in new code.
+
+## Config Migration
+
+### rollupOptions → rolldownOptions
+
+Direct rename. Internal structure (`external`, `output.globals`) stays the same:
+
+```ts
+// Before (Vite 7)
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      external: ['vue'],
+      output: { globals: { vue: 'Vue' } },
+    },
+  },
+})
+
+// After (Vite 8)
+export default defineConfig({
+  build: {
+    rolldownOptions: {
+      external: ['vue'],
+      output: { globals: { vue: 'Vue' } },
+    },
+  },
+})
+```
+
+Also applies to `worker.rollupOptions` → `worker.rolldownOptions`.
+
+### esbuild → oxc (JavaScript Transforms)
+
+Complete mapping of esbuild JSX options to Oxc:
+
+| esbuild | oxc equivalent |
+|---------|---------------|
+| `jsx: 'transform'` | `jsx: { runtime: 'classic' }` |
+| `jsx: 'automatic'` | `jsx: { runtime: 'automatic' }` |
+| `jsx: 'preserve'` | `jsx: 'preserve'` |
+| `jsxFactory: 'h'` | `jsx.pragma: 'h'` |
+| `jsxFragment: 'Fragment'` | `jsx.pragmaFrag: 'Fragment'` |
+| `jsxImportSource: 'react'` | `jsx.importSource: 'react'` |
+| `jsxDev` | `jsx.development` |
+| `jsxSideEffects` | `jsx.pure` |
+| `jsxInject` | `jsxInject` (same) |
+| `include`/`exclude` | `include`/`exclude` (same) |
+| `define` | `define` (same) |
+
+**Not supported in Oxc:** `esbuild.supported` option.
+
+**Not supported:** Native decorator lowering — use Babel or SWC plugins.
+
+**Example — Preact classic JSX:**
+
+```ts
+// Before (Vite 7)
+export default defineConfig({
+  esbuild: {
+    jsxFactory: 'h',
+    jsxFragment: 'Fragment',
+  },
+})
+
+// After (Vite 8)
+export default defineConfig({
+  oxc: {
+    jsx: {
+      runtime: 'classic',
+      pragma: 'h',
+      pragmaFrag: 'Fragment',
+    },
+  },
+})
+```
+
+**Example — React automatic:**
+
+```ts
+export default defineConfig({
+  oxc: {
+    jsx: {
+      runtime: 'automatic',
+      importSource: 'react',
+    },
+  },
+})
+```
+
+### optimizeDeps.esbuildOptions → optimizeDeps.rolldownOptions
+
+Auto-converted options:
+
+| esbuildOptions | rolldownOptions equivalent |
+|---------------|--------------------------|
+| `minify` | `output.minify` |
+| `treeShaking` | `treeshake` |
+| `define` | `transform.define` |
+| `loader` | `moduleTypes` |
+| `preserveSymlinks` | `!resolve.symlinks` |
+| `resolveExtensions` | `resolve.extensions` |
+| `mainFields` | `resolve.mainFields` |
+| `conditions` | `resolve.conditionNames` |
+| `keepNames` | `output.keepNames` |
+| `platform` | `platform` |
+| `plugins` | `plugins` (partial support) |
+
+### Minification
+
+```ts
+// Vite 8 default: Oxc minifier
+build: { minify: true }  // uses Oxc
+
+// Fallback to esbuild (requires installing esbuild)
+build: { minify: 'esbuild' }
+
+// CSS: Lightning CSS is default
+build: { cssMinify: true }           // uses Lightning CSS
+build: { cssMinify: 'esbuild' }     // fallback (requires esbuild)
+```
+
+**Not supported by Oxc minifier:** `mangleProps`, `reserveProps`, `mangleQuoted`, `mangleCache`.
+
+### esbuild.banner/footer
+
+No direct equivalent. Use a custom plugin with the `transform` hook instead.
+
+## Breaking Changes
+
+### manualChunks
+
+- Object form **removed**
+- Function form **deprecated** → use `codeSplitting` option instead
+
+### CommonJS Interop
+
+The `default` import from CJS modules follows new rules. If the importer is `.mjs`/`.mts`, or the closest `package.json` has `"type": "module"`, or `module.exports.__esModule` is not true, then `default` = `module.exports` (not `module.exports.default`).
+
+Temporary workaround: `legacy.inconsistentCjsInterop: true`.
+
+### Format Sniffing Removed
+
+Vite no longer sniffs file content to choose between `browser` and `module` fields. `resolve.mainFields` order is always respected.
+
+### build() Error Handling
+
+`build()` now throws `BundleError` (not raw error) with `.errors?: RolldownError[]` array.
+
+### Removed Config Options
+
+| Removed | Replacement |
+|---------|-------------|
+| `build.commonjsOptions` | No-op (Rolldown handles CJS natively) |
+| `build.dynamicImportVarsOptions.warnOnError` | No-op |
+| `resolve.alias[].customResolver` | Use custom plugin with `resolveId` hook |
+| `rollupOptions.output.manualChunks` (object form) | Use function form or `codeSplitting` |
+| `rollupOptions.watch.chokidar` | `rolldownOptions.watch.watcher` |
+
+### Unsupported Output Formats
+
+`'system'` and `'amd'` output formats are not supported by Rolldown.
+
+### Node.js Requirements
+
+Node.js 20.19+ or 22.12+ required (same as Vite 7).
+
+## Plugin Compatibility
+
+Most Vite/Rollup plugins work unchanged because Rolldown supports the Rollup plugin API. If a plugin only works during build:
+
+```ts
+{
+  ...rollupPlugin(),
+  enforce: 'post',
+  apply: 'build',
+}
+```
+
+**Note:** `moduleParsed` hook is NOT called during dev. Plugins relying on it need adjustment.
+
+Detect Rolldown at runtime: `this.meta.rolldownVersion`.
+
+## Gradual Migration
+
+For large projects, migrate via `rolldown-vite` first:
+
+```bash
+# Step 1: Test with rolldown-vite (still Vite 7)
+pnpm add -D rolldown-vite
+
+# Replace vite import in config
+import { defineConfig } from 'rolldown-vite'
+
+# Step 2: Once stable, upgrade to Vite 8
+pnpm add -D vite@8
+
+# Revert the import
+import { defineConfig } from 'vite'
+```
+
+## Overriding Vite in Frameworks
+
+When framework depends on older Vite:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "vite": "8.0.0"
+    }
+  }
+}
+```
+
+<!--
+Source references:
+- https://vite.dev/blog/announcing-vite8
+- https://vite.dev/guide/migration
+- https://vite.dev/config/shared-options#oxc
+-->