Vite dev server and Docker bind mounts: file watcher interoperability

Direct Answer

Vite's default watcher (chokidar) reliably detects edits through bind mounts on Linux hosts because inotify events propagate into the container. On macOS and Windows using Docker Desktop, the virtualized filesystem layers (gRPC FUSE or 9p) typically do not forward host-side filesystem events to the container. Consequently, HMR will not trigger automatically unless you enable polling (server.watcher.usePolling: true) or move the project files entirely into the Linux filesystem (e.g., the WSL2 /home directory).

Behavior by Platform

Host OS	Event Propagation	Stable Non-Polling Setup
Linux	Native (inotify)	Default bind mounts work.
macOS	Unreliable/None	VirtioFS (experimental) or Linux VM.
Windows	None for /mnt/c/	Store project in WSL2 /home/user/.

Configuration for Stability

Permission and Volume Setup

• UID/GID Matching: To prevent EACCES errors during writes, match the container user to the host user (e.g., user: "1000:1000" in docker-compose.yml). This ensures the container can modify files, though it does not fix watcher events.
• Avoid Cache Flags: Do not rely on :cached or :delegated flags to fix HMR; these optimize read performance but do not enable event propagation.
• Watcher Optimization: Always exclude node_modules and .git via server.watcher.ignored to prevent the watcher from overloading the system.

When Polling is Unavoidable

Polling is the only dependable option when using bind mounts on macOS or Windows (via /mnt/c/). The trade-offs are as follows:

• CPU Impact: For projects under ~5,000 files, polling at a 200–300ms interval typically consumes 5–10% CPU.
• Scaling Limits: Once a project exceeds 20,000 files, polling overhead becomes significant. Monorepos with 50k+ files should avoid polling and use native Linux environments.
• Atomic Writes: Some editors write to a temporary file before renaming. Ensure the polling interval is at least 100ms to avoid missing these rapid changes.

Verification and Implementation

To implement polling in vite.config.js:

export default defineConfig({
  server: {
    watcher: {
      usePolling: true,
      interval: 200,
      useFsEvents: false
    }
  }
});

Verification Steps:

1. Check filesystem backend: docker info (look for VirtioFS or WSL2).
2. Test without polling: Edit a file on the host and check the browser console for HMR updates.
3. Enable polling and monitor resource usage via docker stats.

Missing Diagnostic Detail

Are your project files stored on the Windows host (/mnt/c/...) or inside the WSL2 internal filesystem (/home/...)? If they are in the internal WSL2 filesystem, you can disable polling and regain native performance.