Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 38 ยท Dev Server and HMR

Dependency Pre-Bundling

Understand why Vite pre-bundles node_modules with esbuild, how CommonJS conversion and merging many files work, and how to use optimizeDeps.include, exclude and the cache folder.

The first time you start a Vite project you may see a line such as Optimizing dependencies or a message that new dependencies were found and the page reloaded. That is dependency pre-bundling: the one place where Vite's dev server does bundle. Knowing why it exists, what it changes and how to control it helps you fix confusing development-only bugs.

Vite is not installed on this site, so config and terminal output are read-only. The stand-ins model the two core jobs (merging many files into one and converting CommonJS) in a few lines of Node.js.

Two problems it solves

Source files are served as native ES modules, but packages in node_modules are a different story.

1. Not everything is ESM. Many packages still ship CommonJS (module.exports, require) or UMD. A browser cannot load those with import. Vite must convert them to ES modules so import React from 'react' works.

2. Some packages are made of hundreds of files. lodash-es has more than 600 small modules; some UI libraries re-export thousands of icons. If the browser had to request each one separately, you would see a waterfall of hundreds of requests on every page load and the dev server would crawl.

Pre-bundling uses esbuild to scan your imports, find the packages you use, and build each one into a single ES module file. It runs once, takes a fraction of a second for most projects, and the results are cached in node_modules/.vite/deps.

flowchart LR
  A["Scan your source for bare imports"] --> B["esbuild bundles each package"]
  B --> C["CJS converted to ESM, many files merged into one"]
  C --> D["Cached in node_modules/.vite/deps"]
  D --> E["Browser imports /node_modules/.vite/deps/vue.js?v=hash"]

Your own source code is never pre-bundled: it is served as separate modules.

What you see in the browser

In the Network tab, a package import appears like this:

TEXT
/node_modules/.vite/deps/react.js?v=3f2b9a1c
/node_modules/.vite/deps/react-dom_client.js?v=3f2b9a1c

The v value is a hash of your lockfile, relevant config and patches. When you install or upgrade a package it changes, which invalidates the browser cache. Dependency files are served with Cache-Control: max-age=31536000,immutable, so after the first load they come from the browser cache, and unchanged reloads cost nothing.

Automatic discovery

On the first start, Vite crawls your entry HTML and the modules it imports, collecting bare specifiers, and pre-bundles them. If it later meets an import it did not know about (for example a dynamic import('some-package') that appears only after a click), it:

  1. pre-bundles the new dependency,
  2. prints new dependencies optimized: some-package,
  3. and reloads the page once.

That mid-session reload is harmless but annoying. You can avoid it by listing such packages in optimizeDeps.include.

optimizeDeps options

JavaScript
// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    include: ['lodash-es', 'my-linked-pkg > nested-dep'],
    exclude: ['my-local-esm-lib'],
    force: false,
  },
});

include

Force pre-bundling of packages Vite does not discover on its own. Typical cases:

  • Dynamic or late imports you want warmed up.
  • Linked or monorepo packages that Vite treats as source code (they are not pre-bundled by default) but that import CommonJS dependencies. Use the parent > dep syntax: 'my-linked-pkg > some-cjs-dep'.
  • A CommonJS package imported by an ESM package, which gives a confusing default export error.

exclude

Skip pre-bundling for a package. Only exclude packages that are already valid ESM with few files, such as your own library. Excluding a CommonJS package breaks it in the browser.

force

Ignore the cache and re-bundle everything. The same as the CLI flag vite --force, or deleting node_modules/.vite.

esbuildOptions

Pass options to the esbuild step (target, plugins, define) in unusual cases, such as adding a loader for .js files containing JSX in a dependency.

When the cache goes wrong

Stale pre-bundles cause bugs that look unrelated to dependencies: "the module has no default export", a new package version not taking effect, old code running after switching branches. The fix is always the same:

Terminal
vite --force
# or
rm -rf node_modules/.vite

Vite already invalidates the cache when the lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb), vite.config dependency-related options, NODE_ENV or patches change. It does not notice a change inside a linked package or a manual edit of a file inside node_modules. In that case use --force.

Also remember the browser cache: with DevTools open, tick Disable cache in the Network tab to avoid old immutable files.

Seeing the merge and the conversion

This runnable stand-in models the first job: converting a CommonJS module into something a browser import can use, with a default export and named exports. It is a teaching model, not esbuild.

Node.js Stand-in: CommonJS interop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The second job is merging. This model counts what the browser would have to request before and after pre-bundling for a package made of many small files.

Node.js Stand-in: request count before and after

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Practical tips

  • Do not exclude packages unless you know they are ESM; the usual error ("does not provide an export named default") means the opposite: add the package to include.
  • Large dependency trees may make the first start slower (a second or two). It is a one-off.
  • Library authors: publish ESM so consumers do not need pre-bundling.
  • optimizeDeps.entries lets you override where the crawler looks, useful when your entry points are not index.html, as in some server-rendered setups.
  • npm run build ignores all of this. The production build uses its own bundler pass, so pre-bundling bugs only affect development.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two problems does dependency pre-bundling solve?

    Browsers need ES modules, and hundreds of requests per package would be slow. Pre-bundling fixes both.
  2. 2. Where does Vite cache pre-bundled dependencies?

    The cache lives in node_modules/.vite, and the dependency files are served with immutable cache headers.
  3. 3. A newly discovered dependency makes the page reload during development. How can you avoid it?

    Listing the package in include makes Vite pre-bundle it at startup, so no mid-session discovery is needed.
  4. 4. Which command forces Vite to rebuild the dependency cache?

    vite --force (or deleting node_modules/.vite) ignores cached pre-bundles.

Summary

  • Vite pre-bundles packages from node_modules with esbuild: CommonJS becomes ESM and many-file packages become one file.
  • Results are cached in node_modules/.vite/deps and served with long-lived cache headers.
  • Late-discovered dependencies trigger a one-time reload; list them in optimizeDeps.include to avoid it.
  • Use exclude only for ESM packages, and vite --force to clear a stale cache.
  • Your own source is never pre-bundled, and the production build does not use this step.

Next: Hot Module Replacement