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
Explore agent
- Build analysis: Use
Task agent
- Config review: Delegate to
code-reviewer agent
If the vitest-testing skill is available, delegate test configuration and Vitest setup to it.
If the tailwind skill is available, delegate Tailwind CSS configuration and utility patterns to it.
If the react-patterns skill is available, delegate React component patterns and hooks to it.
If the typescript-patterns skill is available, delegate TypeScript configuration and type patterns to it.
If the pnpm-workspace skill 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
1---2name: vite3description: Vite build tool configuration and ecosystem. Covers vite.config.ts setup, plugin authoring and popular plugins, dev server configuration (proxy, HMR, HTTPS), build optimization (chunking, tree-shaking, manual chunks, rollupOptions), library mode for publishing packages, SSR configuration, environment variables (.env handling), multi-page apps, CSS handling (PostCSS, CSS modules, preprocessors), and asset handling. Use when configuring Vite projects, authoring Vite plugins, optimizing builds, setting up dev server proxies, configuring SSR, handling environment variables, or troubleshooting Vite issues.4license: MIT5---6
7# Vite
8
9## Overview
10
11Vite 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.
12
13**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.
14
15**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.
16
17## Quick Reference
18
19| Pattern | API | Key Points |
20| ------------------ | ------------------------------------------- | --------------------------------- |
21| Config file | `defineConfig({})` | Type-safe config with IDE support |
22| Conditional config | `defineConfig(({ command, mode }) => ({}))` | Different config per command/mode |
23| Path alias | `resolve.alias` | Map `@/` to `src/` |
24| Dev proxy | `server.proxy` | Forward API requests to backend |
25| HMR config | `server.hmr` | WebSocket host/port/protocol |
26| HTTPS dev | `server.https` | Pass TLS cert/key options |
27| Build target | `build.target` | ES module target for output |
28| Manual chunks | `build.rollupOptions.output.manualChunks` | Control code splitting |
29| Library mode | `build.lib` | Publish ES/CJS/UMD packages |
30| SSR build | `build.ssr` + `ssr` options | Server-side rendering config |
31| Env variables | `import.meta.env.VITE_*` | Client-exposed env vars |
32| loadEnv | `loadEnv(mode, root, prefix)` | Load env vars in config |
33| CSS modules | `css.modules` | Scoped CSS class names |
34| Preprocessors | `css.preprocessorOptions` | Sass/Less/Stylus options |
35| PostCSS | `css.postcss` | Inline or external PostCSS config |
36| Static assets | `import url from './img.png'` | Returns resolved public URL |
37| Plugin | `{ name, transform, load }` | Hook-based plugin system |
38| Virtual module | `resolveId` + `load` hooks | Generate modules at build time |
39| Multi-page | `build.rollupOptions.input` | Multiple HTML entry points |
40
41## Common Mistakes
42
43| Mistake | Correct Pattern |
44| --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
45| Exposing secrets via `VITE_` prefix | Only prefix client-safe vars with `VITE_`; use `loadEnv` in config for server-only secrets |
46| Using `process.env` in client code | Use `import.meta.env.VITE_*` (Vite replaces at build time) |
47| Modifying `rollupOptions.input` without `resolve()` | Always use `path.resolve()` or `import.meta.dirname` for absolute paths |
48| Not externalizing peer deps in library mode | Add React/Vue to `rollupOptions.external` to avoid bundling |
49| Creating QueryClient-style singletons in SSR | Ensure per-request state in SSR to avoid cross-request leaks |
50| Inline PostCSS config alongside `postcss.config.js` | Use one or the other; inline config disables config file search |
51| Setting `base` without trailing slash | `base` should be `/path/` with trailing slash or full URL |
52| Using `__dirname` in ESM config | Use `import.meta.dirname` (Node 21+) or `fileURLToPath` |
53
54## Delegation
55
56- **Plugin discovery**: Use `Explore` agent
57- **Build analysis**: Use `Task` agent
58- **Config review**: Delegate to `code-reviewer` agent
59
60> If the `vitest-testing` skill is available, delegate test configuration and Vitest setup to it.
61> If the `tailwind` skill is available, delegate Tailwind CSS configuration and utility patterns to it.
62> If the `react-patterns` skill is available, delegate React component patterns and hooks to it.
63> If the `typescript-patterns` skill is available, delegate TypeScript configuration and type patterns to it.
64> If the `pnpm-workspace` skill is available, delegate monorepo workspace configuration to it.
65
66## References
67
68- [Configuration fundamentals and defineConfig patterns](references/configuration.md)
69- [Plugin authoring and popular plugins](references/plugins.md)
70- [Dev server setup: proxy, HMR, HTTPS, and middleware](references/dev-server.md)
71- [Build optimization: chunking, tree-shaking, and output control](references/build-optimization.md)
72- [Library mode for publishing packages](references/library-mode.md)
73- [SSR configuration and Express integration](references/ssr-configuration.md)
74- [Environment variables and .env file handling](references/environment-variables.md)
75- [CSS handling: PostCSS, CSS modules, preprocessors, and asset management](references/css-and-assets.md)
oakoss