Vite Dependency Pre-Bundling: How esbuild Speeds Up Your Dev Server

Why Vite's dev server can feel slow

When a Vite project depends on many packages distributed as CommonJS or UMD, the dev server must translate those formats to native ES modules on every request. That per-request conversion introduces noticeable pauses, especially on first load and during hot module replacement (HMR).

How pre-bundling works under the hood

Vite serves your source files as native ES modules. That works for code you write, but many npm packages still ship as CommonJS or UMD format. Instead of converting each file at request time, Vite runs esbuild once at startup to bundle all detected dependencies into a small set of ES modules. The result is stored in node_modules/.vite and served from internal routes like /@vite/dep. Because the browser receives a single ES module per dependency graph rather than many individual CommonJS files that need runtime interop, per-request conversion overhead disappears and HMR updates stay responsive.

Controlling pre-bundling with optimizeDeps

You can fine-tune which dependencies get pre-bundled by adjusting the optimizeDeps field in vite.config.js. This is useful when a package breaks during bundling, relies on dynamic imports, or has side effects that esbuild cannot safely resolve.

export default { optimizeDeps: { exclude: ['lodash'] } }

Run the dev server from the project root with a user that can read node_modules. With the exclusion in place, lodash requests are no longer served from /@vite/dep and instead load as individual modules. The console may display a note such as Dependency excluded from optimization: lodash.

To force a dependency into pre-bundling even if it's only referenced via dynamic import, use the include array:

export default { optimizeDeps: { include: ['my-special-package'] } }

Required permissions: The user running the dev server must have read access to node_modules and be able to write to the project root for the .vite cache folder. On shared or restricted environments, cache location can be adjusted, but the default node_modules/.vite works for most local development setups.

Expected checks: After configuring exclude or include, verify that the network tab reflects the expected change (/@vite/dep presence or absence) and that the console emits no unexpected warnings about missing pre-bundling.

Relevant risk: Excluding too many dependencies falls back to native ESM loading for those packages, which can reintroduce the per-request conversion overhead Vite was trying to avoid. Use exclusions sparingly, typically for packages known to fail during bundling.

Trade-offs and verification

Pre-bundling improves dev server performance at the cost of initial startup time for large dependency trees. The first start after clearing the cache is slower because esbuild must walk and bundle the graph. Subsequent restarts reuse the cache and HMR stays fast.

To verify this behavior, delete the node_modules/.vite folder and restart the dev server. The first start should take longer while esbuild re-bundles; later starts should be faster due to caching.

When debugging runtime errors, it can be harder to map a stack trace back to the original source file because you are looking at pre-bundled output. Inspecting the network tab helps confirm which files are served from /@vite/dep versus your source code.

Changes to esbuild options or upgrading Vite may alter the pre-bundled output. After upgrading Vite or modifying optimizeDeps.esbuildOptions, clearing node_modules/.vite and restarting ensures you are not working with stale bundles.

Actionable closing

Keep optimizeDeps focused on the packages that actually cause conversion pain. That preserves the fast HMR benefit without paying unnecessary startup cost. If you are starting a new project, consider starting with a clean optimizeDeps config and only add exclusions or inclusions as needed.