Native OS Events vs. Polling for Large Project File Watching

Answer: Prioritize polling when the OS watch limit cannot be increased or when files are on network mounts; otherwise use native events.

Likely explanation

Native OS events (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows) give near‑instant notifications but each watched file consumes a watch descriptor. The per‑user limit (fs.inotify.max_user_watches) is often 8192. When a project exceeds this number, the watcher silently stops receiving events, causing nodemon to miss restarts. Polling bypasses the descriptor limit by scanning the directory tree at a set interval, guaranteeing eventual detection of changes on any filesystem, including NFS/Samba, at the cost of extra CPU proportional to interval × file count.

Confirmed facts

• Nodemon uses chokidar, which selects native events by default and falls back to polling only when --legacy-watch or NODEMON_POLLING=true is set.
• Increasing fs.inotify.max_user_watches requires root/administrator privileges and may be restricted in containers or CI environments.
• Polling intervals of 500 ms–2 s typically keep CPU usage acceptable for a few thousand files; lower intervals raise CPU load noticeably.

Steps to decide and configure

1. Check the current watch limit: sysctl fs.inotify.max_user_watches (Linux) or the equivalent on macOS/Windows.
2. Estimate the number of files nodemon will watch (e.g., find . -type f | wc -l excluding node_modules).
3. If the file count is comfortably below the limit and the project resides on a local filesystem that propagates events, keep the default native‑event mode.
4. If the count approaches or exceeds the limit, or the files are on NFS/Samba, enable polling:

   nodemon --legacy-watch --poll-interval 1000 src/index.js
   

   or set NODEMON_POLLING=true and optionally legacyWatch: true in nodemon.json with "pollInterval": 1000.
5. Verify CPU impact with top -p $(pgrep nodemon) or ps -o %cpu -p while making frequent changes; adjust the interval upward if CPU usage is excessive.

Missing diagnostic detail

To confirm whether raising the limit is a viable alternative, please provide the current value of fs.inotify.max_user_watches (output of sysctl fs.inotify.max_user_watches). If the limit can be increased without privilege issues, native events may remain the preferred option.