Vite
Overview
Vite is a next-generation frontend build tool that provides instant dev server start via native ES modules and optimized production builds via Rollup. It supports TypeScript, JSX, CSS preprocessors, and static assets out of the box with zero configuration.
When to use: Single-page apps, multi-page apps, library publishing, SSR applications, monorepo packages, any modern frontend project needing fast dev feedback and optimized builds.
When NOT to use: Legacy browsers requiring ES5 output without transpilation, projects locked to Webpack-specific loaders with no Vite equivalents, non-JavaScript build pipelines.
Quick Reference
| Pattern | API | Key Points |
|---|---|---|
| Config file | defineConfig({}) | Type-safe config with IDE support |
| Conditional config | defineConfig(({command, mode}) => ({})) | Different config per command/mode |
| Path alias | resolve.alias | Map @/ to src/ |
| Dev proxy | server.proxy | Forward API requests to backend |
| HMR config | server.hmr | WebSocket host/port/protocol |
| HTTPS dev | server.https | Pass TLS cert/key options |
| Build target | build.target | ES module target for output |
| Manual chunks | build.rollupOptions.output.manualChunks | Control code splitting |
| Library mode | build.lib | Publish ES/CJS/UMD packages |
| SSR build | build.ssr + ssr options | Server-side rendering config |
| Env variables | import.meta.env.VITE_* | Client-exposed env vars |
| loadEnv | loadEnv(mode, root, prefix) | Load env vars in config |
| CSS modules | css.modules | Scoped CSS class names |
| Preprocessors | css.preprocessorOptions | Sass/Less/Stylus options |
| PostCSS | css.postcss | Inline or external PostCSS config |
| Static assets | import url from './img.png' | Returns resolved public URL |
| Plugin | {name, transform, load} | Hook-based plugin system |
| Virtual module | resolveId + load hooks | Generate modules at build time |
| Multi-page | build.rollupOptions.input | Multiple HTML entry points |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
Exposing secrets via VITE_ prefix | Only prefix client-safe vars with VITE_; use loadEnv in config for server-only secrets |
Using process.env in client code | Use import.meta.env.VITE_* (Vite replaces at build time) |
Modifying rollupOptions.input without resolve() | Always use path.resolve() or import.meta.dirname for absolute paths |
| Not externalizing peer deps in library mode | Add React/Vue to rollupOptions.external to avoid bundling |
| Creating QueryClient-style singletons in SSR | Ensure per-request state in SSR to avoid cross-request leaks |
Inline PostCSS config alongside postcss.config.js | Use one or the other; inline config disables config file search |
Setting base without trailing slash | base should be /path/ with trailing slash or full URL |
Using __dirname in ESM config | Use import.meta.dirname (Node 21+) or fileURLToPath |
Delegation
- Plugin discovery: Use
Exploreagent - Build analysis: Use
Taskagent - Config review: Delegate to
code-revieweragent
If thevitest-testingskill is available, delegate test configuration and Vitest setup to it. If thetailwindskill is available, delegate Tailwind CSS configuration and utility patterns to it. If thereact-patternsskill is available, delegate React component patterns and hooks to it. If thetypescript-patternsskill is available, delegate TypeScript configuration and type patterns to it. If thepnpm-workspaceskill is available, delegate monorepo workspace configuration to it.
References
- Configuration fundamentals and defineConfig patterns
- Plugin authoring and popular plugins
- Dev server setup: proxy, HMR, HTTPS, and middleware
- Build optimization: chunking, tree-shaking, and output control
- Library mode for publishing packages
- SSR configuration and Express integration
- Environment variables and.env file handling
- CSS handling: PostCSS, CSS modules, preprocessors, and asset management