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 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

2. 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

3. 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

4. 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

5. 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

6. 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

7. 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

8. 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