Windows Hot Reload Troubleshooting for Vite and Next.js: Make Auto-Refresh Work Reliably

Auto-refresh and Hot Module Replacement (HMR) are expected to update the browser immediately after saving files. On Windows, however, developers frequently experience a confusing behavior: saved changes do not appear until a manual browser refresh, and in some cases the dev server must be restarted. This is not usually caused by application code. It is typically triggered by file watching and reload signaling problems caused by Windows filesystem event behavior.

This guide focuses on practical, high-impact fixes for Vite (React) and Next.js so changes consistently refresh the browser on Windows. It also includes a checklist of additional Windows-specific causes that commonly interfere with HMR, including WSL2 path issues, antivirus interference, IDE save settings, and Docker setups.

Why HMR Fails on Windows

Dev servers rely on a file watcher to detect changes in the project folder. When a file changes, the watcher triggers HMR to push updates to the browser. On macOS and Linux, filesystem notifications are often reliable. On Windows, file watching can miss or delay events, especially on network drives, mounted paths, or containerized environments.

When the watcher fails to detect changes, the dev server never triggers HMR. As a result, the browser shows stale code until a manual refresh forces the browser to reload from the server.

Most Reliable Solution for Vite: Enable Polling

For Vite, the most dependable fix is to enable polling in the dev server. Polling checks for changes at regular intervals instead of relying on filesystem events. This reduces reliance on Windows event delivery.

Step-by-step for Vite

• Open vite.config.ts.
• Add a server.watch.usePolling setting.

Example (vite.config.ts)

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    watch: {
      usePolling: true,
      // optional: interval: 500,
      // lower values refresh faster, higher values reduce CPU
    },
    hmr: {
      host: 'localhost',
    },
  },
})

After saving the config, restart the Vite dev server. Polling changes are not applied to an already running process.

Next.js Fix: Disable Turbopack and Use Webpack

Next.js has two different development bundlers depending on configuration. Many Windows HMR refresh issues are resolved by forcing a configuration that works with polling-based watching.

A key constraint is that some polling strategies only behave as expected with Webpack. In newer Next.js versions, Turbopack is often enabled by default. The practical workaround is to disable Turbopack by running Next.js dev with Webpack.

Step-by-step for Next.js

• Open package.json.
• Update the dev script to explicitly use Webpack.

Example (package.json)

{
  "scripts": {
    "dev": "next dev --webpack"
  }
}

Then restart the dev server and verify that saving files now triggers automatic browser updates.

Additional Windows Causes to Check

If polling and bundler selection do not fully resolve the issue, the cause is usually one of the following. These are common in 2024 to 2025 workflows and remain frequent today.

1) WSL2 with /mnt/c mounted drives

When a project is stored under a mounted Windows drive (for example, under /mnt/c), filesystem event behavior can become unreliable for file watching. A widely used fix is to move the project into the Linux home directory.

Move from /mnt/c/Users/…/project to something like ~/project or /home/username/project.

2) Clear build caches and restart

Stale build output can make HMR look broken even when file watching is fixed.

• For Next.js: remove .next and reinstall dependencies if needed.
• For Vite: remove node_modules and any build output directory like dist if the issue persists.

3) Antivirus and security tools

Real-time scanning can interfere with file watcher responsiveness. Adding the project folder to antivirus exclusions often improves reliability.

4) Docker on Windows

Containerized environments frequently amplify filesystem event issues. The same polling concept is typically required for reliable updates.

5) IDE save behavior in VS Code

If file saves are delayed or occur inconsistently, HMR will not trigger. Disabling settings such as “save on focus change” can reduce missed save events.

6) Long paths and casing mismatches

• Use shorter paths (for example, C:devproject) when possible.
• Ensure import casing matches the actual filename exactly.

Quick Debug Tactics

When the diagnosis is unclear, debugging file watching can confirm whether changes are detected.

• Vite: enable polling and consider adjusting watch patterns if necessary.
• Next.js: run the dev server with debugging options to observe reload behavior.

Practical Fix Order for Fast Results

1. Vite: enable server.watch.usePolling and restart.
2. Next.js: update the dev script to run next dev –webpack and restart.
3. WSL2: move projects out of /mnt/c to a Linux home directory.
4. Caches: clear Next.js .next or Vite build artifacts and reinstall if needed.
5. Environment: check antivirus exclusions, Docker, and IDE save settings.

With polling enabled for Vite and Webpack forced for Next.js, auto-refresh behavior typically becomes consistent on Windows. If problems persist after these changes, the remaining likely causes are environment-specific and usually resolve through the checklist above.