Diagnosing Vite.js Hot Module Replacement (HMR) Failures in Development

Recognizable Condition

When editing a source file while the Vite dev server is running, you notice one of the following:

• Changes appear only after a full page reload.
• The browser console shows no [vite] HMR connected message.
• The Network tab does not list a persistent WebSocket connection to /hot.

Cause & Diagnostic Table

Observed Symptom	Possible Cause
No HMR log, WebSocket missing	HMR disabled via server.hmr: false
HMR log present but updates ignored for specific file types (e.g., .jsx, .vue, .scss)	Missing or outdated framework/plugin for those extensions
HMR works initially, then stops after adding a custom proxy or middleware	Middleware rewriting or proxying the /hot WebSocket URL
Running vite build instead of vite	Build command does not start the dev server or HMR
HMR fails after upgrading Vite	Plugin version mismatch with the new Vite version

Ordered Checks

1. Verify dev server mode

   Run the command that starts the development server:

   # In your project root
   vite

   Ensure you are not invoking vite build or vite preview.

2. Check console for HMR connection

   Open the browser’s developer tools console and look for:

   [vite] HMR connected

   If absent, proceed to the next check.

3. Inspect the WebSocket

   In the Network tab, filter by WS and verify a connection to http://localhost:{port}/hot remains open.

4. Review Vite configuration

   Open vite.config.js (or .ts) and confirm:

   export default defineConfig({
     server: {
       // HMR should be true or omitted
       hmr: true
     }
   });

   If you see hmr: false, change it to true or remove the property.

5. Validate framework plugins

   Determine which file types you are editing and ensure the matching plugin is installed and compatible:

   • React: @vitejs/plugin-react
   • Vue 3: @vitejs/plugin-vue
   • Svelte: @sveltejs/vite-plugin-svelte
   • SCSS/SASS: sass (no extra plugin needed) or vite-plugin-scss if using custom processing.

   Check versions against your Vite version (e.g., npm list vite @vitejs/plugin-react).

6. Audit custom middleware/proxy

   If you have a server.middleware or a proxy (e.g., via http-proxy-middleware or Vite’s server.proxy), ensure they do not interfere with the /hot path. A safe pattern is to exclude it:

   server: {
     proxy: {
       '/api': { target: 'http://localhost:3000', changeOrigin: true },
       // do not proxy /hot
       '^/hot': false
     }
   }

Fixes Tied to Findings

HMR disabled in config

Set server.hmr to true or remove the line, then restart the dev server.

Missing/outdated plugin

Install the correct plugin at a version matching your Vite release:

# Example for React with Vite 5
npm i -D @vitejs/plugin-react@^4.0.0

After installation, restart the dev server.

Middleware/proxy interfering

Adjust the proxy rule to exclude /hot or move the middleware after Vite’s internal handlers. Restart the server and verify the WebSocket reconnects.

Using build command

Switch to vite (or vite dev) for development. Reserve vite build for production builds only.

Plugin version mismatch after Vite upgrade

Upgrade the plugin to the latest compatible version, or consult the plugin’s changelog for breaking changes. Then restart the dev server.

Escalation Criteria

If after performing all checks and applying the corresponding fix:

• The HMR WebSocket still does not connect,
• Console shows errors like Failed to construct 'WebSocket' or net::ERR_CONNECTION_REFUSED,
• Changes continue to require a full reload despite correct configuration,

consider the following steps:

1. Check for conflicting processes on the same port (e.g., another dev server) using lsof -i :{port} or netstat -tlnp.
2. Temporarily disable all custom middleware and plugins to isolate the issue; re‑enable them one by one.
3. Consult the Vite --debug flag for verbose logging: vite --debug.
4. If the problem persists, file an issue on the Vite repository or the specific plugin’s repository, providing the verbose log, your vite.config.js, and package versions.

Limitations and Practical Verification

Even with a correct setup, HMR will not trigger for:

• Files ignored by Vite’s module graph (e.g., assets imported with a query that Vite treats as raw).
• Server‑only code that never reaches the client (Vite will not attempt HMR on Node‑only modules).

To verify that HMR is functioning for a typical client‑side file:

1. Open a component file (e.g., src/App.jsx) in your editor.
2. Make a visible change, such as altering text inside a <h1> tag.
3. Save the file and observe the browser: the text should update instantly without a full page reload.
4. Open the console and confirm you see a log like [vite] HMR update followed by the module name.

If the update appears instantly and the log is present, HMR is working as expected.