Flutter Watcher

A Rust-based tool that watches your Flutter project for file changes and automatically triggers hot reload. Features full keyboard passthrough, allowing you to use all Flutter run commands (r, R, h, q, etc.) just like running flutter run directly.

Features

• 🔥 Automatic hot reload on Dart file changes
• ⌨️ Key passthrough: Send Flutter commands directly (r, R, h, q, etc.)
• 🚀 Spawns and manages Flutter run process
• 👀 Recursive file watching
• ⚡ Debounced reload to prevent excessive reloads
• 🎯 Configurable device targeting
• 🛡️ Graceful shutdown with Ctrl+C

Prerequisites

• Rust (install from rustup.rs)
• Flutter SDK installed and in PATH
• A Flutter project to watch

Installation

From Source

git clone <repository-url>
cd flutter_watcher
cargo build --release

The binary will be available at target/release/flutter_watcher

Install Globally

cargo install --path .

Usage

Basic Usage

Run in the current directory (must be a Flutter project):

flutter_watcher

Specify Flutter Project Path

flutter_watcher --path /path/to/flutter/project

Target Specific Device

flutter_watcher --device chrome
flutter_watcher -d "iPhone 14"

Pass Additional Flutter Arguments

flutter_watcher -- --release
flutter_watcher -- --dart-define=API_URL=https://api.example.com

Complete Example

flutter_watcher --path ./my_app --device chrome -- --dart-define=ENV=dev

How It Works

1. Spawns Flutter Process: Starts flutter run with your specified arguments
2. Watches for Changes: Monitors all .dart files in the project directory
3. Auto-Reload: When a file changes, sends 'r' to the Flutter process stdin
4. Key Passthrough: All keyboard input is forwarded to the Flutter process
5. Debouncing: Waits 500ms between reloads to avoid excessive triggering

Flutter Commands

All Flutter run keyboard commands work seamlessly with flutter_watcher:

• r - Hot reload
• R - Hot restart (clears state)
• h - Display help
• c - Clear the screen
• q - Quit
• d - Detach (keep app running)
• s - Take a screenshot
• w - Dump widget hierarchy
• t - Dump rendering tree
• L - Dump layer tree
• S - Dump accessibility tree
• p - Toggle performance overlay
• P - Toggle performance overlay for specific layers
• a - Toggle timeline events for all widget build methods
• i - Toggle widget inspector
• o - Simulate different operating systems
• z - Toggle elevation checker
• v - Open Flutter DevTools

Simply type any of these commands while flutter_watcher is running, just as you would with flutter run.

Command Line Options

Options:
  -p, --path <PATH>      Path to the Flutter project directory [default: .]
  -d, --device <DEVICE>  Device ID to run Flutter on (optional)
  -h, --help             Print help
  -V, --version          Print version

Additional Flutter arguments can be passed after '--'

Examples

Web Development

flutter_watcher -d chrome

Mobile Development (iOS Simulator)

flutter_watcher -d "iPhone 14 Pro"

Android Emulator

flutter_watcher -d emulator-5554

Desktop Development

flutter_watcher -d macos
flutter_watcher -d windows
flutter_watcher -d linux

Development

Build

cargo build

Run in Development

cargo run -- --path /path/to/flutter/project

Run Tests

cargo test

Troubleshooting

"Flutter process has stopped"

The Flutter process may have crashed or exited. Check the Flutter output above for errors.

"Failed to spawn flutter run process"

Ensure Flutter is installed and available in your PATH:

flutter --version

No Hot Reload Happening

• Ensure you're editing .dart files
• Check that the Flutter process is still running
• Verify the file is within the watched directory

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.