Vite's Dependency Pre-Bundling

Why it exists

Vite's dev server aims for near-instant feedback, but browsers create problems. First, they only understand native ES Modules (ESM), while many npm packages are still CommonJS. Second, making hundreds of HTTP requests for a single dependency with many internal files is extremely slow. Pre-bundling solves both problems before your code is ever served.

The mental model

Think of pre-bundling as a prep cook for your dev server. Before service begins, it takes raw ingredients (CommonJS modules, packages with hundreds of files) and prepares them into a ready-to-use format (a single, browser-friendly ESM file). This makes the main service—loading your page in the browser—fast and efficient.

How it works

On first run, Vite scans your code for "bare imports" like import React from 'react'. It uses these as entry points to bundle your node_modules dependencies into a few optimized files using a fast bundler called Rolldown. This process only happens in development mode. If you add a new dependency while the server is running, Vite detects it, re-bundles on the fly, and reloads the page.

When to use it

Pre-bundling is automatic in Vite's dev server. You only need to manually configure it with optimizeDeps.include when an import isn't directly visible in your source code, for example, if it's injected by a plugin. This tells Vite to bundle it upfront, avoiding a disruptive re-bundle and page reload right after the server starts.

When not to use it

Pre-bundling is a dev-only feature; it does not apply to production builds, which use a separate, more aggressive optimization process. You can also use optimizeDeps.exclude for small dependencies that are already valid ESM, letting the browser load them directly. This is also helpful for linked monorepo packages that you want to treat as source code.

One canonical example

A classic case is lodash-es. Without pre-bundling, import { debounce } from 'lodash-es' would cause the browser to fire over 600 individual HTTP requests to load all of its internal modules. Vite's pre-bundling converts lodash-es into a single JavaScript file, so the browser only makes one request, dramatically improving page load performance during development.