Vite build tool patterns including config, plugins, HMR, env variables, proxy setup, SSR, library mode, dependency pre-bundling, and build optimization. Activate when working with vite.config.ts, Vite plugins, or Vite-based projects.

Vite Patterns Build tool and dev server patterns for Vite 8+ projects. Covers configuration, environment variables, proxy setup, library mode, dependency pre bundling, and common production pitfalls. When to Use Configuring vite.config.ts or vite.config.js Setting up environment variables or .env files Configuring dev server proxy for API backends Optimizing build output (chunks, minification, assets) Publishing libraries with build.lib Troubleshooting dependency pre bundling or CJS/ESM interop Debugging HMR, dev server, or build errors Choosing or ordering Vite plugins How It Works Dev mode serves source files as native ESM — no bundling. Transforms happen on demand per module request, which is why cold starts are fast and HMR is precise. Build mode uses Rolldown (v7+) or Rollup (v5–v6) to bundle the app for production with tree shaking, code splitting, and Oxc based minification. Dependency pre bundling converts CJS/UMD deps to ESM once via esbuild and caches the result under node modules/.vite , so subsequent starts skip the work. Plugins share a unified interface across dev and build — the same plugin object works for both the dev server's on demand transforms and the production pipeline. Environment variables are statically inlined at build time. VITE prefixed vars become public constants in the bundle; everything unprefixed is invisible to client code. Examples Config Structure Basic Config Conditional Config Key Config Options Key Default Description root '.' Project root (where index.html lives) base '/' Public base path for deployed assets envPrefix 'VITE ' Prefix for client exposed env vars build.outDir 'dist' Output directory build.minify 'oxc' Minifier ( 'oxc' , 'terser' , or false ) build.sourcemap false true , 'inline' , or 'hidden' Plugins Essential Plugins Most plugin needs are covered by a handful of well maintained packages. Reach for these before writing your own. Plugin Purpose When to use @vitejs/plugin react swc React HMR + Fast Refresh via SWC Default for React apps (faster than Babel variant) @vitejs/plugin react React HMR + Fast Refresh via Babel Only if you need Babel plugins (emotion, MobX decorators) @vitejs/plugin vue Vue 3 SFC support Vue apps vite plugin checker Runs tsc + ESLint in worker thread with HMR overlay Any TypeScript app — Vite does NOT type check during vite build vite tsconfig paths Honors tsconfig.json paths aliases Any time you already have aliases in tsconfig.json vite plugin dts Emits .d.ts files in library mode Publishing TypeScript libraries vite plugin svgr Imports SVGs as React components React apps using SVGs as components rollup plugin visualizer Bundle treemap/sunburst report Periodic bundle size audits (use enforce: 'post' ) vite plugin pwa Zero config PWA + Workbox Offline capable apps Critical callout: vite build transpiles but does NOT type check. Type errors silently ship to production unless you add vite plugin checker or run tsc noEmit in CI. Authoring Custom Plugins Authoring is rare — most needs are covered by existing plugins. When you do need one, start inline in vite.config.ts and only extract if reused. Key hooks: transform (modify source), resolveId + load (virtual modules), transformIndexHtml (inject into HTML), configureServer (add dev middleware), hotUpdate (custom HMR — replaces deprecated handleHotUpdate in v7+). Virtual modules use the \0 prefix convention — resolveId returns '\0virtual:my id' so other plugins skip it. User code imports 'virtual:my id' . For full plugin API, see [vite.dev/guide/api plugin](https://vite.dev/guide/api plugin). Use vite plugin inspect during development to debug the transform pipeline. HMR API Framework plugins ( @vitejs/plugin react , @vitejs/plugin vue , etc.) handle HMR automatically. Reach for import.meta.hot directly only when building custom state stores, dev tools, or framework agnostic utilities that need to persist state across updates. All import.meta.hot code is tree shaken out of production builds — no guard removal needed. Environment Variables Vite loads .env , .env.local , .env.[mode] , and .env.[mode].local in that order (later overrides earlier); .local files are gitignored and meant for local secrets. Client Side Access Only VITE prefixed vars are exposed to client code: Using Env in Config Security VITE Prefix is NOT a Security Boundary Any variable prefixed with VITE is statically inlined into the client bundle at build time . Minification, base64 encoding, and disabling source maps do NOT hide it. A determined attacker can extract any VITE var from the shipped JavaScript. Rule: Only public values (API URLs, feature flags, public keys) go in VITE vars. Secrets (API tokens, database URLs, private keys) MUST live server side behind an API or serverless function. The loadEnv('') Trap Source Maps in Production Production source maps leak your original source code. Disable them unless you upload to an error tracker (Sentry, Bugsnag) and delete locally afterward: .gitignore Checklist .env.local , .env. .local — local secret overrides dist/ — build output node modules/.vite — pre bundle cache (stale entries cause phantom errors) Server Proxy For WebSocket proxying, add ws: true to the route config. Build Optimization Manual Chunks Performance Avoid Barrel Files Barrel files ( index.ts re exporting everything from a directory) force Vite to load every re exported file even when you import a single symbol. This is the 1 dev server slowdown flagged by the official docs. Be Explicit with Import Extensions Each implicit extension forces up to 6 filesystem checks via resolve.extensions . In large codebases, this adds up. Narrow tsconfig.json allowImportingTsExtensions + resolve.extensions to only the extensions you actually use. Warm Up Hot Path Routes server.warmup.clientFiles pre transforms known hot entries before the browser requests them — eliminating the cold load request waterfall on large apps. Profiling Slow Dev Servers When vite dev feels slow, start with vite profile , interact with the app, then press p+enter to save a .cpuprofile . Load it in [Speedscope](https://www.speedscope.app) to find which plugins are eating time — usually buildStart , config , or configResolved hooks in community plugins. Library Mode When publishing an npm package, use build.lib . Two footguns matter more than config detail: 1. Types are not emitted — add vite plugin dts or run tsc emitDeclarationOnly separately. 2. Peer dependencies MUST be externalized — unlisted peers get bundled into your library, causing duplicate runtime errors in consumers. SSR Externals Bare createServer({ middlewareMode: true }) setups are framework author territory. Most apps should use Nuxt, Remix, SvelteKit, Astro, or TanStack Start instead. What you will tweak as a framework user is the externals config when deps break in SSR: Dependency Pre Bundling Vite pre bundles dependencies to convert CJS/UMD to ESM and reduce request count. Common Pitfalls Dev Does Not Match Build Dev uses esbuild/Rolldown for transforms; build uses Rolldown for bundling. CJS libraries can behave differently between the two. Always verify with vite build && vite preview before deploying. Stale Chunks After Deployment New builds produce new chunk hashes. Users with active sessions request old filenames that no longer exist. Vite has no built in solution. Mitigations: Keep old dist/assets/ files live for a deployment window Catch dynamic import errors in your router and force a page reload Docker and Containers Vite binds to localhost by default, which is unreachable from outside a container: Monorepo File Access Vite restricts file serving to the project root. Packages outside root are blocked: Anti Patterns Process anti patterns: vite preview is NOT a production server — it is a smoke test for the built bundle. Deploy dist/ to a real static host (NGINX, Cloudflare Pages, Vercel static) or use a multi stage Dockerfile. Expecting vite build to type check — it only transpiles. Type errors silently ship to production. Add vite plugin checker or run tsc noEmit in CI. Shipping @vitejs/plugin legacy by default — it bloats bundles ~40%, breaks source map bundle analyzers, and is unnecessary for the 95%+ of users on modern browsers. Gate it on real analytics, not assumption. Hand rolling 30+ resolve.alias entries that duplicate tsconfig.json paths — use vite tsconfig paths instead. Observed in Excalidraw and PostHog; avoid in new projects. Leaving stale node modules/.vite after dep changes — pre bundle cache causes phantom errors. Clear it when switching branches or after patching deps. Quick Reference Pattern When to Use defineConfig Always — provides type inference loadEnv(mode, root, ['VITE ']) Access env vars in config (explicit prefix) vite plugin checker Any TypeScript app (fills the type check gap) vite tsconfig paths Instead of hand rolled resolve.alias optimizeDeps.include CJS deps causing interop issues server.proxy Route API requests to backend in dev server.host: true Docker, containers, remote access server.warmup.clientFiles Pre transform hot path routes build.lib + external Publishing npm packages manualChunks (object) Vendor bundle splitting vite profile Debug slow dev server vite build && vite preview Smoke test prod bundle locally (NOT a prod server) Related Skills frontend patterns — React component patterns docker patterns — containerized dev with Vite nextjs turbopack — alternative bundler for Next.js

vite-patterns