Vite HMR and Browser WebSocket Integration: Managing Module Graph Invalidation

Vite HMR Fallback Triggers

Vite abandons Hot Module Replacement and issues a full page reload when the module graph cannot guarantee a safe incremental update. The decision is made on the server after computing the minimal affected set; the client then either applies the HMR payload or reloads the page.

Conditions that Force a Full Reload

• Any changed module (or a module in its acceptance chain) lacks a valid import.meta.hot.accept handler, or the handler throws/returns false.
• Circular dependencies that create an unresolvable update path – Vite detects the cycle and cannot safely apply incremental changes.
• Syntax errors or runtime exceptions during module transformation that break the module graph.

WebSocket Connection Influence

If the WebSocket link between the dev server and the browser is closed, experiences rapid reconnects, or its message queue is overwhelmed by rapid‑fire file saves, Vite treats the connection as unreliable. In that case it initiates a full reload to resynchronize client and server state, even when the module graph would otherwise support a partial HMR update.

Verification Steps

1. Start vite dev and open the browser console; filter for [HMR] logs.
2. Save a file and observe whether you see [HMR] Update applied (partial) or [HMR] Full reload.
3. To test the accept‑handler condition, temporarily remove or break import.meta.hot.accept in a modified module and save; the console should show a full reload.
4. To test WS influence, open Chrome DevTools → Network, enable offline throttling or add a custom WS frame interceptor, then perform rapid saves; a full reload should occur if the WS is deemed unreliable.
5. Introduce a circular dependency between two ES modules, save one file, and verify that the console logs a fallback to full reload due to the unresolvable cycle.

If you can confirm whether you observe WebSocket close or error events in the DevTools Network tab, that would help determine if the WS state is the primary cause of the reload.