Dependency pre-bundling automatic process
When you run vite for the first time, Vite automatically and transparently pre-bundles your project dependencies before loading your site locally. Dependency pre-bundling only applies in development mode.
dependency pre-bundling
20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
CommonJS and UMD compatibility purpose of pre-bundling
During development, Vite serves all code as native ESM. Vite must convert dependencies shipped as CommonJS or UMD into ESM first. Vite performs smart import analysis so that named imports to CommonJS modules work as expected even if exports are dynamically assigned, such as with React.
Performance improvement purpose of pre-bundling
Vite converts ESM dependencies with many internal modules into a single module to improve subsequent page load performance. For example, lodash-es has over 600 internal modules. Pre-bundling lodash-es into a single module reduces 600+ HTTP requests to just one request.
Automatic dependency discovery in Vite
If an existing cache is not found, Vite crawls source code and automatically discovers dependency imports (bare imports expected to be resolved from node_modules) and uses these as entry points for the pre-bundle. Pre-bundling is performed with Rolldown. After the server starts, if a new dependency import is encountered not already in the cache, Vite re-runs the dep bundling process and reloads the page if needed.
Monorepo linked dependencies handling
In a monorepo setup, Vite automatically detects dependencies not resolved from node_modules and treats the linked dep as source code. It will not attempt to bundle the linked dep, and will analyze the linked dep's dependency list instead. However, this requires the linked dep to be exported as ESM. If not exported as ESM, you can add the dependency to optimizeDeps.include in your config.
Restarting dev server for linked dependency changes
When making changes to a linked dep in a monorepo, restart the dev server with the --force command line option for the changes to take effect.
optimizeDeps.include configuration example
To explicitly include a linked dependency for pre-bundling in a monorepo, add it to the optimizeDeps configuration. Example: export default defineConfig({ optimizeDeps: { include: ['linked-dep'] } })
When to use optimizeDeps.include or exclude
A typical use case for optimizeDeps.include or optimizeDeps.exclude is when you have an import not directly discoverable in source code, such as imports created by plugin transforms. If a dependency is large with many internal modules or is CommonJS, include it. If a dependency is small and already valid ESM, exclude it and let the browser load it directly.
optimizeDeps.rolldownOptions customization
You can further customize Rolldown with the optimizeDeps.rolldownOptions option. For example, adding a Rolldown plugin to handle special files in dependencies or changing the build target.
Pre-bundled dependencies cache location
Vite caches pre-bundled dependencies in node_modules/.vite.
Pre-bundling cache invalidation sources
Vite determines whether it needs to re-run the pre-bundling step based on: package manager lockfile content (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, aube-lock.yaml, or nub.lock), patches folder modification time, relevant fields in vite.config.js if present, and NODE_ENV value. The pre-bundling step only needs to be re-run when one of these has changed.
Force re-bundling of dependencies
To force Vite to re-bundle deps, either start the dev server with the --force command line option, or manually delete the node_modules/.vite cache directory.
Browser cache for pre-bundled dependencies
Resolved dependency requests are strongly cached with HTTP headers max-age=31536000,immutable to improve page reload performance during dev. Once cached, these requests never hit the dev server again. They are auto invalidated by an appended version query if a different version is installed as reflected in the package manager lockfile.
Debugging dependencies with local edits
To debug dependencies by making local edits: (1) Temporarily disable cache via the Network tab of browser devtools, (2) Restart Vite dev server with the --force flag to re-bundle the deps, (3) Reload the page.
optimizeDeps.esbuildOptions deprecated in favor of optimizeDeps.rolldownOptions
The optimizeDeps.esbuildOptions option is now deprecated in Vite 8. Users should migrate to optimizeDeps.rolldownOptions. Vite automatically converts esbuildOptions to rolldownOptions for backward compatibility, but this will be removed in the future.
esbuildOptions to rolldownOptions automatic conversions
Vite 8 automatically converts these esbuildOptions to rolldownOptions: esbuildOptions.minify to rolldownOptions.output.minify; esbuildOptions.treeShaking to rolldownOptions.treeshake; esbuildOptions.define to rolldownOptions.transform.define; esbuildOptions.loader to rolldownOptions.moduleTypes; esbuildOptions.preserveSymlinks to !rolldownOptions.resolve.symlinks; esbuildOptions.resolveExtensions to rolldownOptions.resolve.extensions; esbuildOptions.mainFields to rolldownOptions.resolve.mainFields; esbuildOptions.conditions to rolldownOptions.resolve.conditionNames; esbuildOptions.keepNames to rolldownOptions.output.keepNames; esbuildOptions.platform to rolldownOptions.platform; esbuildOptions.plugins to rolldownOptions.plugins (with partial support).
Pre-bundling with Rolldown
Vite detects bare module imports and performs pre-bundling to improve page loading speed and convert CommonJS / UMD modules to ESM. The pre-bundling step is performed with Rolldown and makes Vite's cold start time significantly faster than any JavaScript-based bundler.
Import URL rewriting for dependencies
Vite rewrites bare module imports to valid URLs like `/node_modules/.vite/deps/my-dep.js?v=f3sf2ebd` so that the browser can import them properly.
Dependencies are strongly cached via HTTP headers
Vite caches dependency requests via HTTP headers. To locally edit or debug a dependency, follow the steps in the dep-pre-bundling guide for managing browser cache.
npm link does not invalidate pre-bundled dependencies
The hash key used to invalidate optimized dependencies depends on package lock contents, applied patches, and Vite config options. Vite will detect when a dependency is overridden using npm overrides and re-bundle on next server start, but Vite will not invalidate dependencies when using npm link. When you link or unlink a dependency, force re-optimization on the next server start using vite --force. Vite recommends using overrides instead, which are supported by every package manager (npm overrides, pnpm overrides, yarn resolutions).