Debug: webpack/Vite hot module replacement not working

Hot module replacement (HMR) doesn't work - changes require a full page reload or don't show up at all.

Diagnose HMR issues:

1. Check WebSocket connection:

Browser DevTools > Network > WS tab
Look for ws://localhost:PORT connection
If missing: firewall/proxy blocking WebSockets

2. Vite HMR issues:

// vite.config.js
export default {
  server: {
    hmr: {
      // Behind proxy/Docker:
      host: 'localhost',
      port: 5173,
      // Or use polling (slow but reliable):
      watch: { usePolling: true },
    }
  }
};

3. Common causes:

• Docker/VM: File system events don't propagate. Use polling:

  // vite.config.js
  server: { watch: { usePolling: true, interval: 100 } }
  

• Wrong export pattern: React Fast Refresh requires components as default/named exports

  // BAD: Anonymous export
  export default () => <div />;
  // GOOD: Named component
  export default function MyComponent() { return <div />; }
  

• State reset: HMR loses component state. Add preserve directive:

  // @refresh reset  (forces full remount)
  

• Circular dependencies: Can break HMR graph
• File outside project root: Won't be watched

4. Force full reload as fallback:
If HMR can't apply a change, it falls back to full reload. Check console for [vite] full reload messages.

HMR preserves application state during development, making iteration much faster. When it breaks, development becomes significantly slower.

Frontend development with hot module replacement