compact-agent 1.10.0 → 1.11.0

package/resources/ecc/skills/vite-patterns/SKILL.md

@@ -0,0 +1,449 @@
+---
+name: vite-patterns
+description: Vite build tool patterns including config, plugins, HMR, env variables, proxy setup, SSR, library mode, dependency pre-bundling, and build optimization. Activate when working with vite.config.ts, Vite plugins, or Vite-based projects.
+origin: ECC
+---
+
+# Vite Patterns
+
+Build tool and dev server patterns for Vite 8+ projects. Covers configuration, environment variables, proxy setup, library mode, dependency pre-bundling, and common production pitfalls.
+
+## When to Use
+
+- Configuring `vite.config.ts` or `vite.config.js`
+- Setting up environment variables or `.env` files
+- Configuring dev server proxy for API backends
+- Optimizing build output (chunks, minification, assets)
+- Publishing libraries with `build.lib`
+- Troubleshooting dependency pre-bundling or CJS/ESM interop
+- Debugging HMR, dev server, or build errors
+- Choosing or ordering Vite plugins
+
+## How It Works
+
+- **Dev mode** serves source files as native ESM — no bundling. Transforms happen on-demand per module request, which is why cold starts are fast and HMR is precise.
+- **Build mode** uses Rolldown (v7+) or Rollup (v5–v6) to bundle the app for production with tree-shaking, code-splitting, and Oxc-based minification.
+- **Dependency pre-bundling** converts CJS/UMD deps to ESM once via esbuild and caches the result under `node_modules/.vite`, so subsequent starts skip the work.
+- **Plugins** share a unified interface across dev and build — the same plugin object works for both the dev server's on-demand transforms and the production pipeline.
+- **Environment variables** are statically inlined at build time. `VITE_`-prefixed vars become public constants in the bundle; everything unprefixed is invisible to client code.
+
+## Examples
+
+### Config Structure
+
+#### Basic Config
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: { '@': new URL('./src', import.meta.url).pathname },
+  },
+})
+```
+
+#### Conditional Config
+
+```typescript
+// vite.config.ts
+import { defineConfig, loadEnv } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig(({ command, mode }) => {
+  const env = loadEnv(mode, process.cwd())   // VITE_ prefixed only (safe)
+
+  return {
+    plugins: [react()],
+    server: command === 'serve' ? { port: 3000 } : undefined,
+    define: {
+      __API_URL__: JSON.stringify(env.VITE_API_URL),
+    },
+  }
+})
+```
+
+#### Key Config Options
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `root` | `'.'` | Project root (where `index.html` lives) |
+| `base` | `'/'` | Public base path for deployed assets |
+| `envPrefix` | `'VITE_'` | Prefix for client-exposed env vars |
+| `build.outDir` | `'dist'` | Output directory |
+| `build.minify` | `'oxc'` | Minifier (`'oxc'`, `'terser'`, or `false`) |
+| `build.sourcemap` | `false` | `true`, `'inline'`, or `'hidden'` |
+
+### Plugins
+
+#### Essential Plugins
+
+Most plugin needs are covered by a handful of well-maintained packages. Reach for these before writing your own.
+
+| Plugin | Purpose | When to use |
+|--------|---------|-------------|
+| `@vitejs/plugin-react-swc` | React HMR + Fast Refresh via SWC | Default for React apps (faster than Babel variant) |
+| `@vitejs/plugin-react` | React HMR + Fast Refresh via Babel | Only if you need Babel plugins (emotion, MobX decorators) |
+| `@vitejs/plugin-vue` | Vue 3 SFC support | Vue apps |
+| `vite-plugin-checker` | Runs `tsc` + ESLint in worker thread with HMR overlay | **Any TypeScript app** — Vite does NOT type-check during `vite build` |
+| `vite-tsconfig-paths` | Honors `tsconfig.json` `paths` aliases | Any time you already have aliases in `tsconfig.json` |
+| `vite-plugin-dts` | Emits `.d.ts` files in library mode | Publishing TypeScript libraries |
+| `vite-plugin-svgr` | Imports SVGs as React components | React apps using SVGs as components |
+| `rollup-plugin-visualizer` | Bundle treemap/sunburst report | Periodic bundle size audits (use `enforce: 'post'`) |
+| `vite-plugin-pwa` | Zero-config PWA + Workbox | Offline-capable apps |
+
+**Critical callout:** `vite build` transpiles but does NOT type-check. Type errors silently ship to production unless you add `vite-plugin-checker` or run `tsc --noEmit` in CI.
+
+#### Authoring Custom Plugins
+
+Authoring is rare — most needs are covered by existing plugins. When you do need one, start inline in `vite.config.ts` and only extract if reused.
+
+```typescript
+// vite.config.ts — minimal inline plugin
+function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',                       // required, must be unique
+    enforce: 'pre',                           // 'pre' | 'post' (optional)
+    apply: 'build',                           // 'build' | 'serve' (optional)
+    transform(code, id) {
+      if (!id.endsWith('.custom')) return
+      return { code: transformCustom(code), map: null }
+    },
+  }
+}
+```
+
+**Key hooks:** `transform` (modify source), `resolveId` + `load` (virtual modules), `transformIndexHtml` (inject into HTML), `configureServer` (add dev middleware), `hotUpdate` (custom HMR — replaces deprecated `handleHotUpdate` in v7+).
+
+**Virtual modules** use the `\0` prefix convention — `resolveId` returns `'\0virtual:my-id'` so other plugins skip it. User code imports `'virtual:my-id'`.
+
+For full plugin API, see [vite.dev/guide/api-plugin](https://vite.dev/guide/api-plugin). Use `vite-plugin-inspect` during development to debug the transform pipeline.
+
+### HMR API
+
+Framework plugins (`@vitejs/plugin-react`, `@vitejs/plugin-vue`, etc.) handle HMR automatically. Reach for `import.meta.hot` directly only when building custom state stores, dev tools, or framework-agnostic utilities that need to persist state across updates.
+
+```typescript
+// src/store.ts — manual HMR for a vanilla module
+if (import.meta.hot) {
+  // Persist state across updates (must MUTATE, never reassign .data)
+  import.meta.hot.data.count = import.meta.hot.data.count ?? 0
+
+  // Cleanup side effects before module is replaced
+  import.meta.hot.dispose((data) => clearInterval(data.intervalId))
+
+  // Accept this module's own updates
+  import.meta.hot.accept()
+}
+```
+
+All `import.meta.hot` code is tree-shaken out of production builds — no guard removal needed.
+
+### Environment Variables
+
+Vite loads `.env`, `.env.local`, `.env.[mode]`, and `.env.[mode].local` in that order (later overrides earlier); `*.local` files are gitignored and meant for local secrets.
+
+#### Client-Side Access
+
+Only `VITE_`-prefixed vars are exposed to client code:
+
+```typescript
+import.meta.env.VITE_API_URL   // string
+import.meta.env.MODE            // 'development' | 'production' | custom
+import.meta.env.BASE_URL        // base config value
+import.meta.env.DEV             // boolean
+import.meta.env.PROD            // boolean
+import.meta.env.SSR             // boolean
+```
+
+#### Using Env in Config
+
+```typescript
+// vite.config.ts
+import { defineConfig, loadEnv } from 'vite'
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd())          // VITE_ prefixed only (safe)
+  return {
+    define: {
+      __API_URL__: JSON.stringify(env.VITE_API_URL),
+    },
+  }
+})
+```
+
+### Security
+
+#### `VITE_` Prefix is NOT a Security Boundary
+
+Any variable prefixed with `VITE_` is **statically inlined into the client bundle at build time**. Minification, base64 encoding, and disabling source maps do NOT hide it. A determined attacker can extract any `VITE_` var from the shipped JavaScript.
+
+**Rule:** Only public values (API URLs, feature flags, public keys) go in `VITE_` vars. Secrets (API tokens, database URLs, private keys) MUST live server-side behind an API or serverless function.
+
+#### The `loadEnv('')` Trap
+
+```typescript
+// BAD: passing '' as the third arg loads ALL env vars — including server secrets —
+// and makes them available to inline into client code via `define`.
+const env = loadEnv(mode, process.cwd(), '')
+
+// GOOD: explicit prefix list
+const env = loadEnv(mode, process.cwd(), ['VITE_', 'APP_'])
+```
+
+#### Source Maps in Production
+
+Production source maps leak your original source code. Disable them unless you upload to an error tracker (Sentry, Bugsnag) and delete locally afterward:
+
+```typescript
+build: {
+  sourcemap: false,                                  // default — keep it this way
+}
+```
+
+#### `.gitignore` Checklist
+
+- `.env.local`, `.env.*.local` — local secret overrides
+- `dist/` — build output
+- `node_modules/.vite` — pre-bundle cache (stale entries cause phantom errors)
+
+### Server Proxy
+
+```typescript
+// vite.config.ts — server.proxy
+server: {
+  proxy: {
+    '/foo': 'http://localhost:4567',                    // string shorthand
+
+    '/api': {
+      target: 'http://localhost:8080',
+      changeOrigin: true,                               // needed for virtual-hosted backends
+      rewrite: (path) => path.replace(/^\/api/, ''),
+    },
+  },
+}
+```
+
+For WebSocket proxying, add `ws: true` to the route config.
+
+### Build Optimization
+
+#### Manual Chunks
+
+```typescript
+// vite.config.ts — build.rolldownOptions
+build: {
+  rolldownOptions: {
+    output: {
+      // Object form: group specific packages
+      manualChunks: {
+        'react-vendor': ['react', 'react-dom'],
+        'ui-vendor': ['@radix-ui/react-dialog', '@radix-ui/react-popover'],
+      },
+    },
+  },
+}
+```
+
+```typescript
+// Function form: split by heuristic
+manualChunks(id) {
+  if (id.includes('node_modules/react')) return 'react-vendor'
+  if (id.includes('node_modules')) return 'vendor'
+}
+```
+
+### Performance
+
+#### Avoid Barrel Files
+
+Barrel files (`index.ts` re-exporting everything from a directory) force Vite to load every re-exported file even when you import a single symbol. This is the #1 dev-server slowdown flagged by the official docs.
+
+```typescript
+// BAD — importing one util forces Vite to load the whole barrel
+import { slash } from '@/utils'
+
+// GOOD — direct import, only the one file is loaded
+import { slash } from '@/utils/slash'
+```
+
+#### Be Explicit with Import Extensions
+
+Each implicit extension forces up to 6 filesystem checks via `resolve.extensions`. In large codebases, this adds up.
+
+```typescript
+// BAD
+import Component from './Component'
+
+// GOOD
+import Component from './Component.tsx'
+```
+
+Narrow `tsconfig.json` `allowImportingTsExtensions` + `resolve.extensions` to only the extensions you actually use.
+
+#### Warm-Up Hot-Path Routes
+
+`server.warmup.clientFiles` pre-transforms known hot entries before the browser requests them — eliminating the cold-load request waterfall on large apps.
+
+```typescript
+// vite.config.ts
+server: {
+  warmup: {
+    clientFiles: ['./src/main.tsx', './src/routes/**/*.tsx'],
+  },
+}
+```
+
+#### Profiling Slow Dev Servers
+
+When `vite dev` feels slow, start with `vite --profile`, interact with the app, then press `p+enter` to save a `.cpuprofile`. Load it in [Speedscope](https://www.speedscope.app) to find which plugins are eating time — usually `buildStart`, `config`, or `configResolved` hooks in community plugins.
+
+### Library Mode
+
+When publishing an npm package, use `build.lib`. Two footguns matter more than config detail:
+
+1. **Types are not emitted** — add `vite-plugin-dts` or run `tsc --emitDeclarationOnly` separately.
+2. **Peer dependencies MUST be externalized** — unlisted peers get bundled into your library, causing duplicate-runtime errors in consumers.
+
+```typescript
+// vite.config.ts
+build: {
+  lib: {
+    entry: 'src/index.ts',
+    formats: ['es', 'cjs'],
+    fileName: (format) => `my-lib.${format}.js`,
+  },
+  rolldownOptions: {
+    external: ['react', 'react-dom', 'react/jsx-runtime'],  // every peer dep
+  },
+}
+```
+
+### SSR Externals
+
+Bare `createServer({ middlewareMode: true })` setups are framework-author territory. Most apps should use Nuxt, Remix, SvelteKit, Astro, or TanStack Start instead. What you *will* tweak as a framework user is the externals config when deps break in SSR:
+
+```typescript
+// vite.config.ts — ssr options
+ssr: {
+  external: ['node-native-package'],           // keep as require() in SSR bundle
+  noExternal: ['esm-only-package'],            // force-bundle into SSR output (fixes most SSR errors)
+  target: 'node',                              // 'node' or 'webworker'
+}
+```
+
+### Dependency Pre-Bundling
+
+Vite pre-bundles dependencies to convert CJS/UMD to ESM and reduce request count.
+
+```typescript
+// vite.config.ts — optimizeDeps
+optimizeDeps: {
+  include: [
+    'lodash-es',                              // force pre-bundle known heavy deps
+    'cjs-package',                            // CJS deps that cause interop issues
+    'deep-lib/components/**',                 // glob for deep imports
+  ],
+  exclude: ['local-esm-package'],             // must be valid ESM if excluded
+  force: true,                                // ignore cache, re-optimize (temporary debugging)
+}
+```
+
+### Common Pitfalls
+
+#### Dev Does Not Match Build
+
+Dev uses esbuild/Rolldown for transforms; build uses Rolldown for bundling. CJS libraries can behave differently between the two. Always verify with `vite build && vite preview` before deploying.
+
+#### Stale Chunks After Deployment
+
+New builds produce new chunk hashes. Users with active sessions request old filenames that no longer exist. Vite has no built-in solution. Mitigations:
+
+- Keep old `dist/assets/` files live for a deployment window
+- Catch dynamic import errors in your router and force a page reload
+
+#### Docker and Containers
+
+Vite binds to `localhost` by default, which is unreachable from outside a container:
+
+```typescript
+// vite.config.ts — Docker/container setup
+server: {
+  host: true,                                  // bind 0.0.0.0
+  hmr: { clientPort: 3000 },                   // if behind a reverse proxy
+}
+```
+
+#### Monorepo File Access
+
+Vite restricts file serving to the project root. Packages outside root are blocked:
+
+```typescript
+// vite.config.ts — monorepo file access
+server: {
+  fs: {
+    allow: ['..'],                             // allow parent directory (workspace root)
+  },
+}
+```
+
+### Anti-Patterns
+
+```typescript
+// BAD: Setting envPrefix to '' exposes ALL env vars (including secrets) to the client
+envPrefix: ''
+
+// BAD: Assuming require() works in application source code — Vite is ESM-first
+const lib = require('some-lib')                // use import instead
+
+// BAD: Splitting every node_module into its own chunk — creates hundreds of tiny files
+manualChunks(id) {
+  if (id.includes('node_modules')) {
+    return id.split('node_modules/')[1].split('/')[0]   // one chunk per package
+  }
+}
+
+// BAD: Not externalizing peer deps in library mode — causes duplicate runtime errors
+// build.lib without rolldownOptions.external
+
+// BAD: Using deprecated esbuild minifier
+build: { minify: 'esbuild' }                  // use 'oxc' (default) or 'terser'
+
+// BAD: Mutating import.meta.hot.data by reassignment
+import.meta.hot.data = { count: 0 }           // WRONG: must mutate properties, not reassign
+import.meta.hot.data.count = 0                 // CORRECT
+```
+
+**Process anti-patterns:**
+
+- **`vite preview` is NOT a production server** — it is a smoke test for the built bundle. Deploy `dist/` to a real static host (NGINX, Cloudflare Pages, Vercel static) or use a multi-stage Dockerfile.
+- **Expecting `vite build` to type-check** — it only transpiles. Type errors silently ship to production. Add `vite-plugin-checker` or run `tsc --noEmit` in CI.
+- **Shipping `@vitejs/plugin-legacy` by default** — it bloats bundles ~40%, breaks source-map bundle analyzers, and is unnecessary for the 95%+ of users on modern browsers. Gate it on real analytics, not assumption.
+- **Hand-rolling 30+ `resolve.alias` entries that duplicate `tsconfig.json` paths** — use `vite-tsconfig-paths` instead. Observed in Excalidraw and PostHog; avoid in new projects.
+- **Leaving stale `node_modules/.vite` after dep changes** — pre-bundle cache causes phantom errors. Clear it when switching branches or after patching deps.
+
+## Quick Reference
+
+| Pattern | When to Use |
+|---------|-------------|
+| `defineConfig` | Always — provides type inference |
+| `loadEnv(mode, root, ['VITE_'])` | Access env vars in config (explicit prefix) |
+| `vite-plugin-checker` | Any TypeScript app (fills the type-check gap) |
+| `vite-tsconfig-paths` | Instead of hand-rolled `resolve.alias` |
+| `optimizeDeps.include` | CJS deps causing interop issues |
+| `server.proxy` | Route API requests to backend in dev |
+| `server.host: true` | Docker, containers, remote access |
+| `server.warmup.clientFiles` | Pre-transform hot-path routes |
+| `build.lib` + `external` | Publishing npm packages |
+| `manualChunks` (object) | Vendor bundle splitting |
+| `vite --profile` | Debug slow dev server |
+| `vite build && vite preview` | Smoke-test prod bundle locally (NOT a prod server) |
+
+## Related Skills
+
+- `frontend-patterns` — React component patterns
+- `docker-patterns` — containerized dev with Vite
+- `nextjs-turbopack` — alternative bundler for Next.js