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
- Dependency Pre-bundling (CRITICAL)
-
deps-include-large-cjs
-
Include large dependencies with many modules
-
deps-exclude-esm
-
Exclude small ESM dependencies
-
deps-force-rebundle
-
Use --force flag for dependency changes
-
deps-hold-until-crawl
-
Configure holdUntilCrawlEnd for startup behavior
-
deps-entries
-
Configure custom entry points for discovery
-
deps-linked-packages
-
Handle linked dependencies in monorepos
- Plugin Performance (CRITICAL)
-
plugin-lazy-imports
-
Use dynamic imports in plugin code
-
plugin-avoid-long-hooks
-
Avoid long operations in startup hooks
-
plugin-transform-early-return
-
Early return in transform hooks
-
plugin-audit-community
-
Audit community plugins for performance
-
plugin-swc-over-babel
-
Use SWC instead of Babel for React
- Bundle Optimization (CRITICAL)
-
bundle-manual-chunks
-
Use manualChunks for vendor splitting
-
bundle-dynamic-imports
-
Use dynamic imports for route-level splitting
-
bundle-analyze
-
Analyze bundle composition
-
bundle-tree-shaking
-
Enable effective tree-shaking
-
bundle-chunk-warning
-
Address large chunk warnings
-
bundle-compression
-
Disable compressed size reporting for large projects
-
bundle-asset-inlining
-
Configure asset inlining threshold
- Import Resolution (HIGH)
-
import-avoid-barrel
-
Avoid barrel file imports
-
import-explicit-extensions
-
Use explicit file extensions
-
import-path-aliases
-
Configure path aliases for clean imports
-
import-svg-strings
-
Import SVGs as strings instead of components
-
import-glob-patterns
-
Use glob imports carefully
- Build Configuration (HIGH)
-
build-modern-target
-
Target modern browsers
-
build-minification
-
Use esbuild for minification
-
build-sourcemaps
-
Disable source maps in production
-
build-css-code-split
-
Enable CSS code splitting
-
build-rolldown
-
Consider Rolldown for faster builds
-
build-output-dir
-
Configure output directory and caching
- Development Server (MEDIUM-HIGH)
-
dev-server-warmup
-
Warm up frequently used files
-
dev-browser-cache
-
Keep browser cache enabled in DevTools
-
dev-fs-limits
-
Increase file descriptor limits on Linux
-
dev-wsl-polling
-
Use polling for WSL file watching
-
dev-https-proxy
-
Configure HTTPS and proxy for development
- CSS Optimization (MEDIUM)
-
css-lightning
-
Use Lightning CSS instead of PostCSS
-
css-avoid-preprocessors
-
Prefer CSS over preprocessors when possible
-
css-modules
-
Use CSS Modules for component styles
-
css-inline-critical
-
Extract critical CSS for initial paint
- Advanced Patterns (LOW-MEDIUM)
-
advanced-ssr-externalize
-
Externalize dependencies for SSR
-
advanced-env-static
-
Use static environment variables
-
advanced-profiling
-
Profile build performance
-
advanced-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