In Vite, what makes the dev server rebuild its `node_modules/.vite` dependency cache, and why can an edit inside a dependency stay invisible until `vite --force`?
answer
- a stored hash, not a file watcher
- the lockfile and the patches folder
- optimizer config and NODE_ENV
- immutable in the browser, versioned by query
- --force, optimizeDeps.force, delete the folder
basics
~20 sVite re-bundles dependencies when a hash of the lockfile, the patches folder's modification time, optimizer-related config and NODE_ENV changes. Vite detects neither an edit inside node_modules nor an npm link, and browsers cache optimized files as immutable.
solid answer
~40 sThe optimizer keeps its output in `node_modules/.vite` (the `cacheDir` option's default) together with a metadata file that holds a hash. On start Vite recomputes that hash from the package manager's lockfile content, the patches folder's modification time, the config fields that affect dependency bundling (among them `resolve`, the plugin names, `optimizeDeps.include` and `exclude`, and the optimizer's own options) and the `NODE_ENV` value. If the hash matches, the cache is reused. Vite detects neither a hand edit inside `node_modules` nor an `npm link`. The browser keeps a second cache: optimized files are served with `max-age=31536000,immutable` behind a `?v=` version query, so once cached they never reach the server again until the query changes. To see a local edit, disable the cache in the network panel, restart with `vite --force` (or set `optimizeDeps.force: true`), then reload.
code
bash · 3 lines# after editing node_modules/recur-rules/index.js to debug it
npx vite --force # ignore node_modules/.vite and re-bundle the dependencies
# then reload the page with the network panel's cache disabledgo deeper
Recall where the cache lives, node_modules/.vite, and the flag that ignores it, vite --force.
Explain the inputs to the hash, namely lockfile, patches folder, optimizer-related config and NODE_ENV, and why Vite detects neither a hand edit nor an npm link.
Separate the disk cache from the immutable browser cache when you debug a stale dependency, and steer teams toward lockfile-recorded overrides instead of links so that invalidation happens on its own.
Weigh developer start-up time against correctness: hash-based reuse makes most starts fast, and the price is a few documented manual steps your team's tooling and onboarding must make obvious.
## Two caches, two rules Pre-bundled dependencies are cached twice, once on disk by the dev server and once in the browser. Each layer has its own rule for when it lets go. | Cache | Where it lives | What invalidates it | |---|---|---| | **Optimizer cache** | `node_modules/.vite/deps`, under the `cacheDir` option (default `node_modules/.vite`) | A changed hash at server start, `vite --force`, `optimizeDeps.force: true`, or deleting the folder | | **Browser cache** | The browser's HTTP cache | A new `?v=` query on the import URL, or the cache being disabled in devtools | ## What goes into the optimizer's hash Next to the optimized files Vite writes a metadata file holding a **lockfile hash** and a **config hash**. On every start it recomputes both and compares them with the stored values. The inputs are: 1. **Lockfile content.** This covers npm, Yarn, pnpm, Bun and a few more. For several package managers Vite reads the copy of the lockfile that the install writes inside `node_modules`, so the hash follows what was actually installed. 2. **The patches folder's modification time**, for package managers that keep dependency patches in a folder rather than in the lockfile. 3. **Config that affects dependency bundling.** In the source this is `root`, `resolve`, `assetsInclude`, the names of all plugins, `optimizeDeps.include` and `exclude`, and the optimizer's own bundler options and plugin names. 4. **The `NODE_ENV` value** (or the mode, when `NODE_ENV` is unset). The optimizer replaces `process.env.NODE_ENV` in dependency code, and many packages choose their development or production code from it. When a hash differs, the terminal says which one: `Re-optimizing dependencies because lockfile has changed`, or `... because vite config has changed`. ## What does not invalidate it - **Editing a file inside `node_modules`.** The optimizer does not hash dependency sources, so your debugging edit leaves the cached bundle in place. - **`npm link` or unlink.** Vite's troubleshooting guide says it "won't invalidate the dependencies when you use a feature like npm link". You have to run `vite --force` after linking or unlinking. - **Edits to your own source files.** Those go through the normal on-demand transform, not the optimizer. - **Unrelated config options**, for example `server.port`, which are not part of the hash. Overrides behave differently. npm's `overrides`, pnpm's overrides and Yarn's resolutions are written into the lockfile, so they change the lockfile hash and are picked up on the next start. That is why the guide recommends overrides over linking. ## Reading the metadata The metadata file is `node_modules/.vite/deps/_metadata.json`. It stores the combined `hash`, the separate `lockfileHash` and `configHash`, the `browserHash` that feeds the `v` query, and the list of optimized packages with the file each one was written to. When a start re-bundles unexpectedly, or fails to, compare these values with what the terminal reports. The two separate hashes tell you straight away whether the lockfile side or the config side moved. ## The browser layer The dev server sends optimized dependencies with `max-age=31536000,immutable`. The guide is blunt: "Once cached, these requests will never hit the dev server again." What moves them is the `v` query on the import URL. It changes when a different version is installed, as the lockfile shows, or when the optimizer bundles afresh. Your own source modules work differently: they get fast `304` revalidation. Two consequences follow: - clearing only the browser cache does not help, because the stale bundle is still on disk; - re-bundling on disk while the browser holds the old URL does not help either, until the page asks for the new URL. ## Seeing a local edit to a dependency The guide's recipe has three steps: 1. Temporarily disable the cache in the browser devtools' network tab. 2. Restart the dev server with `--force` so the dependencies are bundled again. 3. Reload the page. Afterwards, switch the cache back on. Vite's performance guide warns that leaving "Disable Cache" enabled has a big impact on start-up and full-page reload times. ## Forcing a rebuild - **`vite --force`** is the CLI flag that makes the optimizer ignore the cache and re-bundle. - **`optimizeDeps.force: true`** does the same from config. If you commit it, every start pays the full cold-start cost. - **Deleting `node_modules/.vite`** has the same effect by hand. - The **`vite optimize`** command is deprecated, because pre-bundling runs automatically.
- Why does Vite recommend overrides over `npm link` for swapping in a local package?An override is recorded in the lockfile, so it changes the lockfile hash and the optimizer re-bundles on the next start without being asked. A link changes what `node_modules` points to in a way Vite does not detect, so you must run `vite --force` after every link or unlink.
- What does committing `optimizeDeps.force: true` to a shared config cost?Every dev-server start ignores the cache and bundles all dependencies again, so each developer pays the cold-start cost on every start, and the fresh version query makes browsers fetch every optimized file again. It belongs in a debugging session, not in a committed default.
- Why is `NODE_ENV` part of the hash?The optimizer replaces `process.env.NODE_ENV` in dependency code with its value, or with the mode when it is unset, and many packages choose development or production code from it. A bundle produced for one value is wrong for another, so a changed value has to re-bundle.
- Vite watches node_modules and re-bundles a dependency as soon as you edit it.
- Restarting the dev server always rebuilds the dependency cache.
- Vite detects npm link and re-bundles the linked package without --force.
- Changing any vite.config option, such as server.port, re-bundles the dependencies.
- Clearing the browser cache alone makes an edit inside node_modules appear.