@biggora/claude-plugins 1.1.1 → 1.2.2

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

@@ -0,0 +1,222 @@
+---
+name: vite-features
+description: Vite-specific import patterns and runtime features
+---
+
+# Vite Features
+
+## Glob Import
+
+Import multiple modules matching a pattern:
+
+```ts
+const modules = import.meta.glob('./dir/*.ts')
+// { './dir/foo.ts': () => import('./dir/foo.ts'), ... }
+
+for (const path in modules) {
+  modules[path]().then((mod) => {
+    console.log(path, mod)
+  })
+}
+```
+
+### Eager Loading
+
+```ts
+const modules = import.meta.glob('./dir/*.ts', { eager: true })
+// Modules loaded immediately, no dynamic import
+```
+
+### Named Imports
+
+```ts
+const modules = import.meta.glob('./dir/*.ts', { import: 'setup' })
+// Only imports the 'setup' export from each module
+
+const defaults = import.meta.glob('./dir/*.ts', { import: 'default', eager: true })
+```
+
+### Multiple Patterns
+
+```ts
+const modules = import.meta.glob(['./dir/*.ts', './another/*.ts'])
+```
+
+### Negative Patterns
+
+```ts
+const modules = import.meta.glob(['./dir/*.ts', '!**/ignored.ts'])
+```
+
+### Custom Queries
+
+```ts
+const svgRaw = import.meta.glob('./icons/*.svg', { query: '?raw', import: 'default' })
+const svgUrls = import.meta.glob('./icons/*.svg', { query: '?url', import: 'default' })
+```
+
+## Asset Import Queries
+
+### URL Import
+
+```ts
+import imgUrl from './img.png'
+// Returns resolved URL: '/src/img.png' (dev) or '/assets/img.2d8efhg.png' (build)
+```
+
+### Explicit URL
+
+```ts
+import workletUrl from './worklet.js?url'
+```
+
+### Raw String
+
+```ts
+import shaderCode from './shader.glsl?raw'
+```
+
+### Inline/No-Inline
+
+```ts
+import inlined from './small.png?inline'    // Force base64 inline
+import notInlined from './large.png?no-inline'  // Force separate file
+```
+
+### Web Workers
+
+```ts
+import Worker from './worker.ts?worker'
+const worker = new Worker()
+
+// Or inline:
+import InlineWorker from './worker.ts?worker&inline'
+```
+
+Preferred pattern using constructor:
+
+```ts
+const worker = new Worker(new URL('./worker.ts', import.meta.url), {
+  type: 'module',
+})
+```
+
+### WebAssembly (Vite 8: works in SSR too)
+
+```ts
+import init from './module.wasm?init'
+const instance = await init()
+```
+
+## Environment Variables
+
+### Built-in Constants
+
+```ts
+import.meta.env.MODE      // 'development' | 'production' | custom
+import.meta.env.BASE_URL  // Base URL from config
+import.meta.env.PROD      // true in production
+import.meta.env.DEV       // true in development
+import.meta.env.SSR       // true when running in server
+```
+
+### Custom Variables
+
+Only `VITE_` prefixed vars exposed to client:
+
+```
+# .env
+VITE_API_URL=https://api.example.com
+DB_PASSWORD=secret  # NOT exposed to client
+```
+
+```ts
+console.log(import.meta.env.VITE_API_URL) // works
+console.log(import.meta.env.DB_PASSWORD)  // undefined
+```
+
+### Mode-specific Files
+
+```
+.env                # always loaded
+.env.local          # always loaded, gitignored
+.env.[mode]         # only in specified mode
+.env.[mode].local   # only in specified mode, gitignored
+```
+
+### TypeScript Support
+
+```ts
+// vite-env.d.ts
+interface ImportMetaEnv {
+  readonly VITE_API_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+```
+
+### HTML Replacement
+
+```html
+<p>Running in %MODE%</p>
+<script>window.API = "%VITE_API_URL%"</script>
+```
+
+## CSS
+
+### CSS Modules
+
+Any `.module.css` file treated as CSS module:
+
+```ts
+import styles from './component.module.css'
+element.className = styles.button
+```
+
+### Lightning CSS (Vite 8 default for minification)
+
+Lightning CSS is now the default CSS minifier. For full Lightning CSS processing:
+
+```ts
+export default defineConfig({
+  css: {
+    transformer: 'lightningcss',
+    lightningcss: {
+      // Lightning CSS options
+    },
+  },
+})
+```
+
+## JSON Import
+
+```ts
+import pkg from './package.json'
+import { version } from './package.json'  // Named import with tree-shaking
+```
+
+## HMR API
+
+```ts
+if (import.meta.hot) {
+  import.meta.hot.accept((newModule) => {
+    // Handle update
+  })
+
+  import.meta.hot.dispose((data) => {
+    // Cleanup before module is replaced
+  })
+
+  import.meta.hot.invalidate()  // Force full reload
+}
+```
+
+<!--
+Source references:
+- https://vite.dev/guide/features
+- https://vite.dev/guide/env-and-mode
+- https://vite.dev/guide/assets
+- https://vite.dev/guide/api-hmr
+-->

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
+-->