Vite HMR triggering full page reloads during module invalidation

The short answer

Vite abandons a partial HMR update and issues a full page reload when the changed module's update cannot be accepted anywhere along its import chain. There is no configuration option to suppress that fallback — including for circular dependencies. The fix is structural: give the update a valid HMR boundary or break the cycle.

Likely explanation vs. confirmed behavior

Confirmed (well-established behavior, Vite 2.x–5.x): When a file changes, Vite walks the module graph from the changed module upward, looking for a module that calls import.meta.hot.accept() — an "HMR boundary." If the walk reaches a dead end (an importer that neither accepts the update nor has its own boundary above it), Vite cannot safely apply a partial update and tells the client to reload the whole page. You can see this in the browser console as [vite] hot update followed by a full reload, plus a fresh request for the HTML document.

Likely explanation for your case: A circular import (a.js imports b.js, b.js imports a.js) makes the propagation walk ambiguous. Vite cannot determine a safe order in which to re-execute the modules in the cycle without risking stale bindings, so it conservatively treats the cycle as having no usable boundary and falls back to a reload. This is a deliberate safety choice, not a bug.

Conditions that force a full reload

• The changed module has no import.meta.hot.accept handler and no importer up the chain accepts it either.
• The update path passes through a circular dependency Vite cannot order safely.
• The changed file is the HTML entry, vite.config.js, or a file outside the module graph that Vite treats as a hard dependency (e.g., index.html, some env/config files).
• A module invalidates itself without accepting (calling import.meta.hot.invalidate() in a context with no boundary above).

What you can actually do

1. Add a boundary. In the nearest stable parent module, accept the child update: if (import.meta.hot) { import.meta.hot.accept('./child.js', (mod) => { /* re-apply */ }) }. Framework plugins (React, Vue, Svelte) already inject these boundaries for components — full reloads in a framework app usually mean the edited file isn't a component the plugin recognizes.
2. Break the cycle. Extract the shared code that both modules need into a third module that neither imports back into. This is the only reliable fix for cycle-triggered reloads.
3. Don't chase a config flag. server.hmr: false disables HMR entirely (every change reloads), and server.hmr: { overlay: false } only hides the error overlay — neither changes the fallback decision.

Verify it yourself

npm create vite@latest hmr-test -- --template vanilla
cd hmr-test && npm install && npm run dev

Create a.js importing b.js and b.js importing a.js, import one of them from main.js, then edit and save. The console shows the full-reload fallback. Then remove the cycle and save again — the update applies without a reload.

Uncertainty

Exact propagation heuristics have been refined across Vite versions; the behavior above reflects the long-standing design, but if you need version-specific guarantees, state your Vite version and check its changelog. If your reloads happen even without cycles, the missing diagnostic is which file you edited — entry-adjacent files reload by design.