Vite HMR Not Working— Hot Module Replacement Fixed [2026]
Also covers: file watcher limits · WSL2 polling · React Fast Refresh · HMR host config · full page reload causes
⚡ Symptoms
[vite] page reloaded ← full reload instead of HMR update
[vite] server connection lost ← WebSocket dropped
# OR: edits don't update browser at all
# OR: component state resets on every save (Fast Refresh not working)✅ Fastest diagnostics
1. Browser console: look for '[vite] connected.' on load
2. Linux/WSL2: check file watcher limit → sudo sysctl fs.inotify.max_user_watches
3. WSL2 editing Windows files → enable usePolling in vite.config.ts
4. React: confirm @vitejs/plugin-react is in vite.config.ts pluginsWhy Vite HMR Stops Working
Vite HMR relies on two things: the OS file watcher detecting file changes, and a WebSocket connection from the browser to the dev server. If either breaks, HMR fails. On Linux and WSL2, the inotify watcher limit is often hit in large projects. In Docker and WSL2 with Windows files, polling is required instead.
Increase OS File Watcher Limit (Linux/WSL2)
ENOSPC: System limit for number of file watchers reachedError: ENOSPC: System limit for number of file watchers reached# Check current limit
cat /proc/sys/fs/inotify/max_user_watches
# Temporary fix (resets on reboot)
sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl -p
# Permanent fix — add to /etc/sysctl.conf
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
# For WSL2 — add to /etc/sysctl.d/99-vite.conf
sudo sh -c 'echo "fs.inotify.max_user_watches=524288" > /etc/sysctl.d/99-vite.conf'Enable Polling for WSL2 and Network Drives
WSL2 editing Windows files — inotify doesn't receive eventsimport { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
export default defineConfig({
plugins: [react()],
server: {
watch: {
// ✅ Use polling when inotify doesn't work (WSL2, Docker, NFS, network drives)
usePolling: true,
interval: 100, // poll every 100ms — lower = faster but more CPU
},
},
})
// Only enable polling when needed — it uses more CPU than inotify.
// Set via env variable to avoid committing it for teammates on macOS/Windows:
export default defineConfig({
server: {
watch: {
usePolling: process.env.VITE_USE_POLLING === "true",
},
},
})
// Then in .env.local (gitignored): VITE_USE_POLLING=trueFix React Fast Refresh Not Working
State resets on every save — Fast Refresh not activatingReact Fast Refresh only activates when a file exports only React components. Mixing component and non-component exports in the same file disables Fast Refresh for that file.
// vite.config.ts — ensure @vitejs/plugin-react is present
import react from "@vitejs/plugin-react"
export default defineConfig({ plugins: [react()] })
// ❌ Mixing component + non-component export — disables Fast Refresh
// components/Button.tsx:
export const BUTTON_SIZES = ["sm", "md", "lg"] as const // ← constant — breaks Fast Refresh
export function Button({ size }) { return <button /> }
// ✅ Move constants to a separate file
// constants/button.ts:
export const BUTTON_SIZES = ["sm", "md", "lg"] as const
// components/Button.tsx — only exports the component:
export function Button({ size }) { return <button /> }
// ❌ Anonymous default export — Fast Refresh can't track it
export default () => <div>Hello</div>
// ✅ Named function component as default export
export default function HomePage() { return <div>Hello</div> }The Vite console logs a warning when Fast Refresh is disabled for a file: '(!) Could not Fast Refresh Button.tsx. Export of non-component detected.' Move non-component exports to separate files to re-enable Fast Refresh.
Configure HMR Host and Port Explicitly
HMR disconnects when accessed via proxy, tunnel, or custom hostexport default defineConfig({
server: {
host: "0.0.0.0", // bind to all interfaces (needed for Docker/remote access)
port: 5173,
hmr: {
// Explicitly set HMR WebSocket host and port
// Needed when Vite is behind a reverse proxy or accessed via tunnel
host: "localhost",
port: 5173,
protocol: "ws", // or "wss" for HTTPS
// For ngrok or remote tunnels:
// host: "your-tunnel-id.ngrok.io",
// protocol: "wss",
// clientPort: 443,
},
},
})
// For Docker — override via environment:
// VITE_ALLOW_EXTERNAL_ORIGIN=true or configure allowedHosts:
export default defineConfig({
server: {
allowedHosts: ["myapp.local", ".ngrok.io"],
},
})Identify Modules That Cause Full-Page Reloads
Specific file edits always trigger full reload — find the boundaryVite logs the reason for a full page reload in the browser console and terminal. Use this to identify which modules have no HMR boundary.
// Browser console — Vite HMR messages:
// [vite] connected. ← WebSocket connected
// [vite] hot updated: /src/components/Button.tsx ← successful HMR
// [vite] page reloaded ← full reload (no HMR boundary)
// Terminal — Vite dev server logs:
// hmr update /src/components/Button.tsx
// hmr invalidate /src/main.tsx The update boundary is out of date.
// Common causes of full page reload:
// 1. File exports non-React values alongside components
// 2. Module is in the HMR boundary root (e.g. main.tsx imports everything)
// 3. Circular imports break the HMR graph
// 4. CSS-in-JS or runtime style injection without HMR support
// Fix — add explicit HMR accept at the module level if needed:
// (advanced — usually not required)
if (import.meta.hot) {
import.meta.hot.accept() // this module handles its own HMR updates
}Prevention
- On Linux/WSL2, set fs.inotify.max_user_watches=524288 permanently in /etc/sysctl.conf
- Use VITE_USE_POLLING=true in .env.local for WSL2 with Windows files — keep it gitignored
- Export only React components from each .tsx file — move constants and utils to separate files
- Use named function components as default exports — anonymous () => <div> breaks Fast Refresh
- Configure server.hmr.host explicitly when running Vite behind a proxy, Docker, or ngrok tunnel
- Watch the Vite console for '(!) Could not Fast Refresh' warnings — they tell you exactly which file breaks HMR
Frequently Asked Questions
Why does Vite do a full page reload instead of HMR?+−
Why does Vite HMR not work in WSL2?+−
What is React Fast Refresh and how does it differ from HMR?+−
How do I check if Vite HMR is connected?+−
Can I disable HMR in Vite?+−
Why does editing a CSS file cause a full page reload in Vite?+−
Need Expert Help?
We Build React Apps with Vite
Softplix engineers configure Vite for fast HMR, optimised builds, and production-ready React apps. Let us help.
Talk to an Engineer