Vite Best Practices
This edition was verified against stable vite@8.2.2 (August 2026). Vite 8 uses Rolldown for dependency optimization and production builds, Oxc for JavaScript transforms and minification, and Lightning CSS for CSS minification.
For version-sensitive work, confirm the project's installed Vite version first. If the user requests the latest version, also confirm the current latest npm dist-tag and use the matching official documentation; do not apply Vite 8-only options to older projects unless the task includes migration.
Workflow
- Inspect
package.json, the lockfile, vite.config.*, framework plugins, and the scripts that actually invoke Vite. Frameworks may own or wrap Vite configuration.
- Separate the requested fix from an upgrade. Preserve the installed major/minor unless the user asks to migrate or the requested API requires it.
- Prefer a Vite-level option over low-level Rolldown/Oxc customization. Preserve existing JavaScript vs TypeScript and ESM conventions instead of rewriting the config format without need.
- Treat release-candidate and experimental APIs as opt-in. State their status and compatibility limits, pin the Vite minor when relying on them, and add them only when the use case justifies the risk.
- Verify with the repository's own checks. At minimum, run the relevant typecheck or config load plus a production build; exercise dev/HMR or SSR behavior when the change affects those paths.
Vite 8 Configuration Names
Use current names in new or migrated Vite 8 configuration. Compatibility aliases still work but are deprecated:
| Deprecated alias |
Current option |
build.rollupOptions |
build.rolldownOptions |
worker.rollupOptions |
worker.rolldownOptions |
esbuild |
oxc |
optimizeDeps.esbuildOptions |
optimizeDeps.rolldownOptions |
build.minify: 'esbuild' |
build.minify: 'oxc' (default for client builds) |
Do not mechanically rename nested options without checking the migration mapping. Some esbuild and Rollup options changed shape, are unsupported, or require a plugin-based replacement.
Current Stable Capabilities
- Vite 8.2 adds top-level
input, shared by dev, dependency optimization, normal builds, library mode, and SSR unless a more specific entry overrides it.
resolve.tsconfigPaths is stable and opt-in. It follows TypeScript files/include matching and does not resolve Less imports.server.forwardConsole is enabled automatically when Vite detects a coding agent; configure it only when explicit log levels or deterministic behavior are needed.- Vite 8.1 adds case-insensitive
import.meta.glob, direct WebAssembly ESM imports, and custom HTML asset-source discovery.
- Lightning CSS is the default CSS minifier. Full CSS processing with
css.transformer: 'lightningcss' remains experimental; PostCSS is the default transformer.
- Bundled dev mode, chunk import maps, Devtools integration, and parts of the Environment API are not fully stable. Do not enable them as generic defaults.
Reference Routing
Read only the references relevant to the task:
| Task |
Reference |
| Config loading, entries, aliases, Oxc, console forwarding, Devtools |
core-config |
| Imports, assets, env variables, CSS, Wasm, HMR |
core-features |
| Plugin hooks, virtual modules, hook filters, plugin compatibility |
core-plugin-api |
| Production builds, chunking, libraries, MPA, SSR, JavaScript API |
build-and-ssr |
| Custom runtimes or multi-environment framework/plugin work |
environment-api |
Vite 7 to 8 or rolldown-vite migration |
rolldown-migration |
Verification Guidance
- Use the package manager recorded by the lockfile; do not regenerate a different lockfile.
- Prefer project scripts such as
typecheck, build, and existing tests over ad hoc commands.
- For a config-only smoke check, run the real Vite command or build so Vite resolves the config and plugins.
- For library changes, inspect emitted formats, exports, CSS, and declaration generation separately; Vite does not generate TypeScript declarations by itself.
- For SSR changes, verify both client and server builds and at least one rendered request.
- Report experimental or unverified runtime paths explicitly instead of treating a successful client build as complete proof.
Official Sources
1---2name: vite-best-practices3description: Configure, migrate, debug, or review Vite applications, libraries, SSR integrations, and plugins. Use for vite.config files, HMR, import.meta APIs, Vite environment variables, Rolldown/Oxc migration, dependency optimization, or the Environment API; do not use for framework behavior that does not involve Vite.4---56# Vite Best Practices78This edition was verified against stable `vite@8.2.2` (August 2026). Vite 8 uses Rolldown for dependency optimization and production builds, Oxc for JavaScript transforms and minification, and Lightning CSS for CSS minification.910For version-sensitive work, confirm the project's installed Vite version first. If the user requests the latest version, also confirm the current `latest` npm dist-tag and use the matching official documentation; do not apply Vite 8-only options to older projects unless the task includes migration.1112## Workflow13141. Inspect `package.json`, the lockfile, `vite.config.*`, framework plugins, and the scripts that actually invoke Vite. Frameworks may own or wrap Vite configuration.152. Separate the requested fix from an upgrade. Preserve the installed major/minor unless the user asks to migrate or the requested API requires it.163. Prefer a Vite-level option over low-level Rolldown/Oxc customization. Preserve existing JavaScript vs TypeScript and ESM conventions instead of rewriting the config format without need.174. Treat release-candidate and experimental APIs as opt-in. State their status and compatibility limits, pin the Vite minor when relying on them, and add them only when the use case justifies the risk.185. Verify with the repository's own checks. At minimum, run the relevant typecheck or config load plus a production build; exercise dev/HMR or SSR behavior when the change affects those paths.1920## Vite 8 Configuration Names2122Use current names in new or migrated Vite 8 configuration. Compatibility aliases still work but are deprecated:2324| Deprecated alias | Current option |25|------------------|----------------|26| `build.rollupOptions` | `build.rolldownOptions` |27| `worker.rollupOptions` | `worker.rolldownOptions` |28| `esbuild` | `oxc` |29| `optimizeDeps.esbuildOptions` | `optimizeDeps.rolldownOptions` |30| `build.minify: 'esbuild'` | `build.minify: 'oxc'` (default for client builds) |3132Do not mechanically rename nested options without checking the migration mapping. Some esbuild and Rollup options changed shape, are unsupported, or require a plugin-based replacement.3334## Current Stable Capabilities3536- Vite 8.2 adds top-level `input`, shared by dev, dependency optimization, normal builds, library mode, and SSR unless a more specific entry overrides it.37- `resolve.tsconfigPaths` is stable and opt-in. It follows TypeScript `files`/`include` matching and does not resolve Less imports.38- `server.forwardConsole` is enabled automatically when Vite detects a coding agent; configure it only when explicit log levels or deterministic behavior are needed.39- Vite 8.1 adds case-insensitive `import.meta.glob`, direct WebAssembly ESM imports, and custom HTML asset-source discovery.40- Lightning CSS is the default CSS **minifier**. Full CSS processing with `css.transformer: 'lightningcss'` remains experimental; PostCSS is the default transformer.41- Bundled dev mode, chunk import maps, Devtools integration, and parts of the Environment API are not fully stable. Do not enable them as generic defaults.4243## Reference Routing4445Read only the references relevant to the task:4647| Task | Reference |48|------|-----------|49| Config loading, entries, aliases, Oxc, console forwarding, Devtools | [core-config](references/core-config.md) |50| Imports, assets, env variables, CSS, Wasm, HMR | [core-features](references/core-features.md) |51| Plugin hooks, virtual modules, hook filters, plugin compatibility | [core-plugin-api](references/core-plugin-api.md) |52| Production builds, chunking, libraries, MPA, SSR, JavaScript API | [build-and-ssr](references/build-and-ssr.md) |53| Custom runtimes or multi-environment framework/plugin work | [environment-api](references/environment-api.md) |54| Vite 7 to 8 or `rolldown-vite` migration | [rolldown-migration](references/rolldown-migration.md) |5556## Verification Guidance5758- Use the package manager recorded by the lockfile; do not regenerate a different lockfile.59- Prefer project scripts such as `typecheck`, `build`, and existing tests over ad hoc commands.60- For a config-only smoke check, run the real Vite command or build so Vite resolves the config and plugins.61- For library changes, inspect emitted formats, exports, CSS, and declaration generation separately; Vite does not generate TypeScript declarations by itself.62- For SSR changes, verify both client and server builds and at least one rendered request.63- Report experimental or unverified runtime paths explicitly instead of treating a successful client build as complete proof.6465## Official Sources6667- [Vite guide](https://vite.dev/guide/)68- [Configuration reference](https://vite.dev/config/)69- [Vite 8 migration guide](https://vite.dev/guide/migration)70- [Release policy and supported versions](https://vite.dev/releases)71- [Vite changelog](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md)
biggora