In Vite, when should a dependency go in `optimizeDeps.include` rather than `optimizeDeps.exclude`, and why does excluding a CommonJS package break it?
answer
- force in, or keep out
- linked packages count as source
- large or CommonJS means include
- small and valid ESM means exclude
- 'esm-dep > cjs-dep' for a nested one
basics
~20 sInclude forces a dependency into pre-bundling: a linked CommonJS package, a large many-module package, or an import the scan cannot see. Exclude suits a small, already valid ESM package; an excluded CommonJS package reaches the browser unconverted and fails.
solid answer
~50 s`optimizeDeps.include` adds packages to pre-bundling and `optimizeDeps.exclude` takes them out. Include a dependency when the optimizer would otherwise skip or miss it. That covers a linked workspace package that ships CommonJS (linked packages outside `node_modules` are treated as source and not pre-bundled by default), a package with many internal modules or deep imports, and an import the start-up scan cannot see. Exclude a dependency only when it is small and already valid ESM, so the browser can load it directly. Excluding a CommonJS package means Vite serves the package's own file unchanged, and a browser module has no `require` or `module.exports`, so the import fails. If an excluded ESM package depends on a CommonJS one, keep the nested package optimized with `include: ['esm-dep > cjs-dep']`. Both lists feed the optimizer's cache hash, so editing either one re-bundles on the next start.
code
typescript · 12 lines// vite.config.ts
import { defineConfig } from 'vite'
export default defineConfig({
optimizeDeps: {
include: [
'@branchcal/shared', // linked workspace package that ships CommonJS
'cal-widgets > recur-rules', // CommonJS dependency of an excluded package
],
exclude: ['cal-widgets'], // small package already shipped as ESM
},
})go deeper
Recall the direction of each list: include forces a package into pre-bundling, exclude keeps it out, and CommonJS packages must never be excluded.
Explain why linked packages are served as source, when that needs include, and how the parent > child form keeps a nested CommonJS dependency optimized under an excluded parent.
Judge each entry by format and size, read the network panel to confirm what is optimized, and remember both lists feed the cache hash, so every change costs a re-bundle on the next start.
Set a policy for shared configs: keep include and exclude short and justified per package, because each entry is a hand-maintained exception to automatic discovery that outlives the reason it was added.
## Two lists that point opposite ways Vite's dependency optimizer decides by itself which packages to pre-bundle: everything the start-up scan finds as a bare import that resolves into `node_modules`. Two options override that decision. Both are arrays of package names, both apply only to the development optimizer, and both are part of the hash that decides whether the optimizer's cache is still valid. | Option | What it does | Typical candidates | |---|---|---| | `optimizeDeps.include` | Forces the listed packages into pre-bundling | A linked package that ships CommonJS, a large many-module package, an import the scan cannot see, a set of deep imports | | `optimizeDeps.exclude` | Keeps the listed packages out; the browser loads their files directly | A small package already shipped as valid ESM | ## When include is the right call - **A linked package that is CommonJS.** In the calendar's monorepo, `@branchcal/shared` resolves to a workspace folder outside `node_modules`. Vite notices this and treats the package as **source code**: it does not bundle it, and pre-bundles the package's own dependencies instead. That works only when the linked package is ESM. If it ships CommonJS, list it in `include`. After you edit an included linked package, restart with `--force` so the change is bundled again. - **An import the scan cannot see.** If a plugin's transform adds the import, the scan misses it and the optimizer re-runs once the browser requests the file. Listing the package moves its optimization to start-up. - **A large package.** The guide's rule of thumb is that a dependency that is "large (with many internal modules) or is CommonJS" should be included. - **Many deep imports.** `include` accepts a trailing glob, still marked experimental, such as `'cal-widgets/components/**/*.vue'`. It pre-bundles every matching deep import at once instead of re-running the optimizer each time a new one is used. ## When exclude is the right call The guide's case for `exclude` is narrow: a dependency that is "small and is already valid ESM" can be left out, and the browser loads it directly. The costs are real, though small for such a package: - each of its internal files becomes its own request; - it gets none of the optimizer's CommonJS handling, so it must not depend on CommonJS packages that the browser would then receive raw. ## A worked decision for the calendar | Package | Format and shape | Decision | |---|---|---| | `recur-rules` | CommonJS only | Leave it to discovery; never exclude it | | `cal-utils-es` | ESM, six hundred internal modules | Leave it to discovery; add to `include` only if its import is found late | | `@branchcal/shared` | Linked workspace package that ships CommonJS | `include` | | `rich-notes-editor` | ESM, imported where the scan cannot see it | `include` | | `cal-widgets` | Small, valid ESM | May be excluded, with its CommonJS child included | Most packages need neither list. Each entry is a deliberate exception to automatic discovery, so each one should have a reason you can state. ## Why excluding a CommonJS package breaks The docs give a flat warning: "CommonJS dependencies should not be excluded from optimization." Here is what happens if you exclude `recur-rules` anyway: 1. The optimizer leaves the package alone, so the app's import is served as the package's own CommonJS file. 2. The browser loads that file as an ES module. It uses `require`, `module` and `exports`, and it declares no ES exports at all. 3. The import fails. A named or default import finds no matching export when the module graph is linked, or the code throws as soon as it touches `require` or `module`. The exact message differs between browsers. ## The nested case Suppose `cal-widgets` is a small ESM package you exclude, but it imports `recur-rules`, which is CommonJS. With the parent excluded, the docs say the nested CommonJS package should be added to `include`, written with the `>` syntax: ```js optimizeDeps: { exclude: ['cal-widgets'], include: ['cal-widgets > recur-rules'], } ``` The `parent > child` form names the nested dependency through the package that imports it. ## Checking your choice - **Network panel.** An optimized package loads from `/node_modules/.vite/deps/…?v=…`. An excluded one loads from its own files, often many requests. - **Terminal.** After you change either list, the next start logs that it is re-optimizing because the Vite config changed, since `include` and `exclude` are both part of the config hash. - **Scope.** Neither list changes what `vite build` produces. The options in this section apply only to the dependency optimizer, and the optimizer runs only in development.
- Why does a linked workspace package skip pre-bundling by default?Vite sees that it does not resolve from `node_modules` and treats it as source code: it serves the package's files the way it serves the app's own and pre-bundles that package's dependencies instead. That keeps edits to the package visible without re-bundling, but it requires the package to be ESM; a CommonJS linked package must go in `optimizeDeps.include`.
- How does `include` help with a package used through many deep imports?It accepts a trailing glob, still experimental, such as `'cal-widgets/components/**/*.vue'`. Every matching deep import is pre-bundled at start-up, so each deep import a developer starts using does not set off another optimizer run.
- What happens after you edit `include` or `exclude`?Both lists are part of the config hash the optimizer stores with its cache. On the next dev-server start the hash no longer matches, Vite logs that it is re-optimizing because the config changed, and it bundles the dependencies again.
- Excluding a CommonJS package is a safe way to save optimizer work.
- Linked workspace packages are always pre-bundled like packages in node_modules.
- An excluded ESM package needs nothing extra when it imports a CommonJS package.
- optimizeDeps.include also changes what vite build bundles for production.
- Every dependency should be excluded so the browser loads packages straight from node_modules.