npm package: @raphaellcs/file-watcher
Description: Watch files and run commands on changes
Author: Dream Heart
Latest version: 1.0.0

# @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

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

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

## Usage

### Basic Usage

```bash
# 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

```bash
# 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

```bash
# 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:

```json
{
  "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

```bash
$ 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

```bash
$ 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

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

### Example 4: Watch for Add and Change Events

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

### Example 5: Configuration File

Create `.watcher.json`:

```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:

```bash
$ 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:

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

### Chain Multiple Commands

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

### Verbose Mode for Debugging

```bash
$ 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](https://www.npmjs.com/package/@raphaellcs/file-watcher)
- [GitHub](https://github.com/RaphaelLcs-financial/file-watcher)