Vite Best Practices
Comprehensive performance optimization guide for Vite applications. Contains 42 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when:
- Configuring Vite for a new project
- Troubleshooting slow dev server startup
- Optimizing production bundle size
- Debugging HMR issues
- Writing or evaluating Vite plugins
- Migrating from Webpack or other bundlers
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Dependency Pre-bundling | CRITICAL | deps- |
| 2 | Plugin Performance | CRITICAL | plugin- |
| 3 | Bundle Optimization | CRITICAL | bundle- |
| 4 | Import Resolution | HIGH | import- |
| 5 | Build Configuration | HIGH | build- |
| 6 | Development Server | MEDIUM-HIGH | dev- |
| 7 | CSS Optimization | MEDIUM | css- |
| 8 | Advanced Patterns | LOW-MEDIUM | advanced- |
Quick Reference
1. Dependency Pre-bundling (CRITICAL)
deps-include-large-cjs- Include large dependencies with many modulesdeps-exclude-esm- Exclude small ESM dependenciesdeps-force-rebundle- Use --force flag for dependency changesdeps-hold-until-crawl- Configure holdUntilCrawlEnd for startup behaviordeps-entries- Configure custom entry points for discoverydeps-linked-packages- Handle linked dependencies in monorepos
2. Plugin Performance (CRITICAL)
plugin-lazy-imports- Use dynamic imports in plugin codeplugin-avoid-long-hooks- Avoid long operations in startup hooksplugin-transform-early-return- Early return in transform hooksplugin-audit-community- Audit community plugins for performanceplugin-swc-over-babel- Use SWC instead of Babel for React
3. Bundle Optimization (CRITICAL)
bundle-manual-chunks- Use manualChunks for vendor splittingbundle-dynamic-imports- Use dynamic imports for route-level splittingbundle-analyze- Analyze bundle compositionbundle-tree-shaking- Enable effective tree-shakingbundle-chunk-warning- Address large chunk warningsbundle-compression- Disable compressed size reporting for large projectsbundle-asset-inlining- Configure asset inlining threshold
4. Import Resolution (HIGH)
import-avoid-barrel- Avoid barrel file importsimport-explicit-extensions- Use explicit file extensionsimport-path-aliases- Configure path aliases for clean importsimport-svg-strings- Import SVGs as strings instead of componentsimport-glob-patterns- Use glob imports carefully
5. Build Configuration (HIGH)
build-modern-target- Target modern browsersbuild-minification- Use esbuild for minificationbuild-sourcemaps- Disable source maps in productionbuild-css-code-split- Enable CSS code splittingbuild-rolldown- Consider Rolldown for faster buildsbuild-output-dir- Configure output directory and caching
6. Development Server (MEDIUM-HIGH)
dev-server-warmup- Warm up frequently used filesdev-browser-cache- Keep browser cache enabled in DevToolsdev-fs-limits- Increase file descriptor limits on Linuxdev-wsl-polling- Use polling for WSL file watchingdev-https-proxy- Configure HTTPS and proxy for development
7. CSS Optimization (MEDIUM)
css-lightning- Use Lightning CSS instead of PostCSScss-avoid-preprocessors- Prefer CSS over preprocessors when possiblecss-modules- Use CSS Modules for component stylescss-inline-critical- Extract critical CSS for initial paint
8. Advanced Patterns (LOW-MEDIUM)
advanced-ssr-externalize- Externalize dependencies for SSRadvanced-env-static- Use static environment variablesadvanced-profiling- Profile build performanceadvanced-lib-mode- Configure library mode for package development
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
Reference Files
| File | Description |
|---|---|
| AGENTS.md | Complete compiled guide with all rules |
| references/_sections.md | Category definitions and ordering |
| assets/templates/_template.md | Template for new rules |
| metadata.json | Version and reference information |