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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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.
origin
Multiversal
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.
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.
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.jsonpaths 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. 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.
// src/store.ts — manual HMR for a vanilla moduleif (import.meta.hot) {
// Persist state across updates (must MUTATE, never reassign .data)import.meta.hot.data.count = import.meta.hot.data.count ?? 0// Cleanup side effects before module is replacedimport.meta.hot.dispose((data) =>clearInterval(data.intervalId))
// Accept this module's own updatesimport.meta.hot.accept()
}
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:
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
// BAD: passing '' as the third arg loads ALL env vars — including server secrets —// and makes them available to inline into client code via `define`.const env = loadEnv(mode, process.cwd(), '')
// GOOD: explicit prefix listconst env = loadEnv(mode, process.cwd(), ['VITE_', 'APP_'])
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:
build: {
sourcemap: false, // default — keep it this way
}
.gitignore Checklist
.env.local, .env.*.local — local secret overrides
dist/ — build output
node_modules/.vite — pre-bundle cache (stale entries cause phantom errors)
// Function form: split by heuristicmanualChunks(id) {
if (id.includes('node_modules/react')) return'react-vendor'if (id.includes('node_modules')) return'vendor'
}
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.
// BAD — importing one util forces Vite to load the whole barrelimport { slash } from'@/utils'// GOOD — direct import, only the one file is loadedimport { slash } from'@/utils/slash'
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.jsonallowImportingTsExtensions + 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.
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 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:
Types are not emitted — add vite-plugin-dts or run tsc --emitDeclarationOnly separately.
Peer dependencies MUST be externalized — unlisted peers get bundled into your library, causing duplicate-runtime errors in consumers.
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:
// vite.config.ts — ssr optionsssr: {
external: ['node-native-package'], // keep as require() in SSR bundlenoExternal: ['esm-only-package'], // force-bundle into SSR output (fixes most SSR errors)target: 'node', // 'node' or 'webworker'
}
Dependency Pre-Bundling
Vite pre-bundles dependencies to convert CJS/UMD to ESM and reduce request count.
// vite.config.ts — optimizeDepsoptimizeDeps: {
include: [
'lodash-es', // force pre-bundle known heavy deps'cjs-package', // CJS deps that cause interop issues'deep-lib/components/**', // glob for deep imports
],
exclude: ['local-esm-package'], // must be valid ESM if excludedforce: true, // ignore cache, re-optimize (temporary debugging)
}
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:
// BAD: Setting envPrefix to '' exposes ALL env vars (including secrets) to the clientenvPrefix: ''// BAD: Assuming require() works in application source code — Vite is ESM-firstconst lib = require('some-lib') // use import instead// BAD: Splitting every node_module into its own chunk — creates hundreds of tiny filesmanualChunks(id) {
if (id.includes('node_modules')) {
return id.split('node_modules/')[1].split('/')[0] // one chunk per package
}
}
// BAD: Not externalizing peer deps in library mode — causes duplicate runtime errors// build.lib without rolldownOptions.external// BAD: Using deprecated esbuild minifierbuild: { minify: 'esbuild' } // use 'oxc' (default) or 'terser'// BAD: Mutating import.meta.hot.data by reassignmentimport.meta.hot.data = { count: 0 } // WRONG: must mutate properties, not reassignimport.meta.hot.data.count = 0// CORRECT
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
