watch-run

Run any command when files change. Cross-platform, zero dependencies.

Unlike nodemon (Node.js-only), entr (Unix-only), and chokidar-cli (needs deps), watch-run works anywhere Node.js runs.

Install

npm install -g watch-run

Or without installing:

npx watch-run -- node server.js

Usage

watch-run -- node server.js             # Restart server on any file change
watch-run --ext "js,ts" -- npm test     # Run tests when JS/TS files change
watch-run --dir src/ --clear -- node build.js  # Build when src changes, clear screen
watch-run --ext py -- python app.py     # Python auto-reload
watch-run --poll -- go run .            # Use polling (network drives / older Linux)

Example Output

watch-run  .
  Watching [js,ts] · command: npm test
  Debounce: 300ms · Ctrl+C to stop

10:24:31  ▶ npm test  (triggered by src/utils.js)

  PASS src/utils.test.js
  PASS src/api.test.js

10:24:34  ✓ exit 0

10:24:45  ▶ npm test  (triggered by src/api.js)

  FAIL src/api.test.js
    ● should return 404 for missing user

10:24:47  ✗ exit 1

Options

| Flag | Default | Description | |---|---|---| | --dir <path> | . | Directory to watch | | --ext <list> | all files | Extensions: --ext "js,ts,py" | | --ignore <list> | node_modules,.git,dist,build | Comma-separated patterns to ignore | | --delay <ms> | 300 | Debounce delay — wait this long after last change | | --clear | off | Clear terminal before each run | | --poll | off | Use polling instead of fs.watch | | --poll-interval <ms> | 1000 | Polling interval (requires --poll) | | --once | off | Run once then exit (useful for testing) |

Platform Notes

| Platform | Method | Notes | |---|---|---| | Windows | fs.watch recursive | Native, reliable | | macOS | fs.watch recursive | Uses FSEvents | | Linux (Node ≥22) | fs.watch recursive | inotify-based | | Linux (Node <22) | auto-falls back to --poll | | | Network drives | --poll | fs.watch unreliable over NFS/SMB |

vs. Alternatives

| Tool | Runtime | Windows | Any command | Zero-dep | |---|---|---|---|---| | nodemon | Node | ✓ | Node.js only | ❌ | | entr | binary | ❌ | ✓ | ✓ | | chokidar-cli | Node | ✓ | ✓ | ❌ | | watchman | binary | ❌ | ✓ | ❌ | | watch-run | Node | ✓ | ✓ | ✓ |

License

MIT

Keywords

file watcher · watch files · nodemon alternative · entr alternative · run on change · rerun command · live reload · fs watch · cross-platform · zero dependencies

Built to solve, shared to help — Rushabh Shah 🛠️✨

One of 40+ zero-dependency developer CLI tools — no node_modules, ever.