vite-errors-dependency

vite-errors-dependency

Quick Reference

Pre-Bundling Overview

Vite pre-bundles dependencies in dev mode ONLY. It converts CJS/UMD packages to ESM and collapses large dependency trees into single modules. The cache lives at node_modules/.vite.

Version	Pre-Bundling Engine	Config Key for Engine Options
Vite 5	esbuild	optimizeDeps.esbuildOptions
Vite 6–7	esbuild	optimizeDeps.esbuildOptions
Vite 8	Rolldown	optimizeDeps.rolldownOptions

NEVER assume pre-bundling affects production builds. Production uses Rollup (v5–v7) or Rolldown (v8) natively with @rollup/plugin-commonjs or built-in CJS support.

Critical Warnings

NEVER exclude a CJS dependency from pre-bundling via optimizeDeps.exclude. The browser cannot load CommonJS modules natively. Excluding a CJS package breaks module resolution at runtime.

NEVER edit files inside node_modules/ without also clearing the Vite cache (node_modules/.vite) and using --force. The browser aggressively caches pre-bundled deps with max-age=31536000,immutable.

ALWAYS add linked monorepo dependencies that do NOT export ESM to optimizeDeps.include. Vite skips pre-bundling for linked deps by default, assuming they are ESM source code.

ALWAYS restart the dev server with --force after modifying linked dependency source code in a monorepo.

---

Debugging Flowchart

Dev server error or unexpected behavior with a dependency?
│
├─ Error: "Failed to resolve import" or "does not provide an export named"
│  ├─ Is the package CJS-only?
│  │  ├─ YES → Is it in optimizeDeps.exclude?
│  │  │  ├─ YES → REMOVE it from exclude. CJS MUST be pre-bundled.
│  │  │  └─ NO  → Add to optimizeDeps.include explicitly.
│  │  └─ NO (ESM) → Check package.json "exports" field for correct conditions.
│  │
│  └─ Is it a monorepo linked dep?
│     ├─ Does it export ESM? → No action needed (Vite treats as source).
│     └─ Does it export CJS? → Add to optimizeDeps.include.
│
├─ Error: "Outdated pre-bundle" or stale module content
│  ├─ Did you manually edit node_modules/?
│  │  ├─ YES → Run: vite --force AND clear browser cache.
│  │  └─ NO  → Delete node_modules/.vite, restart dev server.
│  └─ Check: Did lockfile, vite.config, NODE_ENV, or patches change?
│     └─ YES → Vite should auto-invalidate. If not, run: vite --force.
│
├─ Slow dev server startup (many HTTP requests)
│  ├─ Check Network tab: hundreds of requests to one dependency?
│  │  └─ YES → Add that dependency to optimizeDeps.include.
│  │     Example: lodash-es triggers 600+ module requests without pre-bundling.
│  └─ Check: Are there undiscovered deps from plugin transforms?
│     └─ YES → Add to optimizeDeps.include (auto-discovery misses these).
│
└─ Import works in dev but fails in production (or vice versa)
   └─ Pre-bundling is dev-only. Production uses a different CJS handling path.
      Check build output for CJS interop issues separately.