@raphaellcs/file-watcher

A simple and powerful file watcher that runs commands automatically when files change.

Features

• 👀 Watch files and directories for changes
• 🔄 Auto-run commands on file changes
• ⚡ Debounce to prevent rapid-fire command execution
• 🔍 Filter files by pattern
• 📁 Recursive directory watching
• 📝 Config file support for complex setups
• 🎯 Event filtering (add, change, unlink)

Installation

# Use with npx (no installation needed)
npx @raphaellcs/file-watcher --help

# Or install globally
npm install -g @raphaellcs/file-watcher

Usage

Basic Usage

# Watch current directory and run tests on changes
npx @raphaellcs/file-watcher watch -c "npm test"

# Watch specific directory
npx @raphaellcs/file-watcher watch -p src -c "npm run build"

# Watch JavaScript files only
npx @raphaellcs/file-watcher watch -p src -c "npm test" -f "*.js"

Advanced Options

# Custom debounce interval (1000ms)
npx @raphaellcs/file-watcher watch -p src -c "npm test" -i 1000

# Watch only add and change events
npx @raphaellcs/file-watcher watch -p src -c "npm test" -e "add,change"

# Quiet mode (suppress output)
npx @raphaellcs/file-watcher watch -p src -c "npm test" -q

# Verbose mode (show detailed logs)
npx @raphaellcs/file-watcher watch -p src -c "npm test" -v

Using Configuration File

# Create a configuration file
npx @raphaellcs/file-watcher init

# Edit .watcher.json
npx @raphaellcs/file-watcher watch-config --config .watcher.json

Configuration File

Create a .watcher.json file in your project:

{
  "watch": "src",
  "command": "npm test",
  "debounce": 300,
  "recursive": true,
  "filter": "*.{js,ts,json}",
  "events": ["change", "add"],
  "quiet": false,
  "verbose": true
}

Configuration Options:

• watch: Path to watch (default: .)
• command: Command to run on changes
• debounce: Debounce interval in milliseconds (default: 300)
• recursive: Watch recursively (default: true)
• filter: File pattern to watch (default: *)
• events: Events to watch: add, change, unlink (default: change)
• quiet: Suppress non-error output (default: false)
• verbose: Show detailed logs (default: false)

Options

Watch Command

• -p, --path <path> - Path to watch (default: current directory)
• -c, --command <cmd> - Command to run on changes
• -i, --interval <ms> - Debounce interval in milliseconds (default: 300)
• -r, --recursive - Watch recursively (default: true)
• -f, --filter <pattern> - File pattern to watch (default: *)
• -e, --events <events> - Events to watch: add, change, unlink (default: change)
• -q, --quiet - Suppress non-error output
• -v, --verbose - Show detailed logs

Examples

Example 1: Run Tests on File Changes

$ npx @raphaellcs/file-watcher watch -p src -c "npm test"

👀 Watching: /project/src
Command: npm test
Debounce: 300ms
Events: change
Filter: *
Press Ctrl+C to stop

✓ Watching for changes...

✓ Changes detected, running command...
Running: npm test

  PASS  src/app.test.js
  ✓ tests pass

✓ Command completed in 1234ms

Example 2: Auto-rebuild Project

$ npx @raphaellcs/file-watcher watch -p src -c "npm run build" -f "*.js" -i 1000

👀 Watching: /project/src
Command: npm run build
Debounce: 1000ms
Events: change
Filter: *.js
Press Ctrl+C to stop

✓ Watching for changes...

Example 3: Watch Multiple File Types

$ npx @raphaellcs/file-watcher watch -p src -c "npm test" -f "*.{js,ts,json}"

Example 4: Watch for Add and Change Events

$ npx @raphaellcs/file-watcher watch -p assets -c "npm run optimize" -e "add,change"

Example 5: Configuration File

Create .watcher.json:

{
  "watch": "src",
  "command": "npm run lint && npm test",
  "debounce": 500,
  "recursive": true,
  "filter": "*.{js,jsx,ts,tsx}",
  "events": ["change"],
  "quiet": false,
  "verbose": true
}

Run:

$ npx @raphaellcs/file-watcher watch-config

👀 Watching: /project/src
Command: npm run lint && npm test
Debounce: 500ms
Events: change
Filter: *.{js,jsx,ts,tsx}
Press Ctrl+C to stop

✓ Watching for changes...

Use Cases

• 🧪 Testing: Auto-run tests when source code changes
• 🏗️ Building: Rebuild project on file changes
• 🔍 Linting: Run linter automatically
• 📦 Bundling: Rebundle on changes
• 🚀 Hot Reload: Restart server on changes
• 📄 Documentation: Build docs on markdown changes
• 🎨 Styles: Recompile CSS/SASS on changes

Advanced Patterns

Watch Multiple Directories

Use separate watcher processes or use shell to watch multiple paths:

npx @raphaellcs/file-watcher watch -p src -c "npm run build" &
npx @raphaellcs/file-watcher watch -p tests -c "npm test" &

Chain Multiple Commands

npx @raphaellcs/file-watcher watch -p src -c "npm run lint && npm test && npm run build"

Verbose Mode for Debugging

$ npx @raphaellcs/file-watcher watch -p src -c "npm test" -v

[change] app.js
[change] utils.js

✓ Changes detected, running command...
Changed files:
  - app.js
  - utils.js
Running: npm test

✓ Command completed in 1234ms

Performance Tips

• Use filter: Limit to specific file types to reduce noise
• Increase debounce: Use higher debounce for long-running commands
• Exclude node_modules: Files starting with . are automatically ignored
• Quiet mode: Use -q in production to reduce output

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

License

MIT

Author

Dream Heart 🌙

Links

• npm
• GitHub