flutter-w

A CLI wrapper for Flutter that provides automatic hot reload and hot restart on file changes, making Flutter development easier in any text editor or terminal.

Features

  • Automatic Hot Reload: Watches Dart files and triggers hot reload when changes are detected
  • Automatic Hot Restart: Watches configuration files (like pubspec.yaml) and triggers hot restart when modified
  • Editor Agnostic: Works with any text editor or IDE - no Flutter plugin required
  • Flexible File Watching: Configure which paths to watch for reload or restart
  • Pass-through Arguments: Supports all Flutter run arguments
  • Debouncing: Prevents excessive reloads with configurable debounce timing

Installation

Prerequisites

  1. Flutter SDK installed and in your PATH
  2. Dart SDK (comes with Flutter)
  3. Xcode and Command Line Tools (for iOS development on macOS)

Install via Dart pub

dart pub global activate --source path /path/to/flutter-watch-cli

Or if you have the package published:

dart pub global activate flutter_w

Make sure your Dart global packages are in your PATH:

export PATH="$PATH":"$HOME/.pub-cache/bin"

Usage

Basic Usage

Start Flutter with auto hot-reload on file changes:

flutter-w run

Specify Device

Run on a specific device:

flutter-w run -d ios
flutter-w run -d "iPhone 15"
flutter-w run -d chrome

Custom Watch Paths

Watch specific directories or files:

# Watch lib and assets for hot reload
flutter-w run -w lib -w assets

# Watch pubspec.yaml and config files for hot restart
flutter-w run -W pubspec.yaml -W config/

Pass Arguments to Flutter

Pass additional arguments to Flutter run using --:

flutter-w run -d ios -- --flavor staging
flutter-w run -d chrome -- --web-renderer canvaskit

All Options

OPTIONS:
  -d, --device <id>         Device id/name (passes through to flutter run -d)
  -w, --watch <path>        Paths/globs to hot reload on change (repeatable)
                            (default: lib)
  -W, --restart-watch <p>   Paths/globs to hot restart on change (repeatable)
                            (default: pubspec.yaml)
  -b, --debounce <ms>       Debounce milliseconds (default: 200)
  -v, --verbose             Verbose logging
      --no-run              Only print the flutter command, don't execute
  -h, --help                Show help

How It Works

  1. Process Management: Spawns flutter run as a child process
  2. File Watching: Uses Dart's watcher package to monitor file system changes
  3. Hot Reload/Restart: Sends keyboard commands (r for reload, R for restart) to the Flutter process
  4. Debouncing: Groups rapid file changes together to avoid excessive reloads

Examples

Development with Hot Reload

# Basic development
flutter-w run

# iOS Simulator with verbose logging
flutter-w run -d ios -v

# Web development with custom renderer
flutter-w run -d chrome -- --web-renderer html

Custom Watch Configuration

# Watch multiple directories
flutter-w run -w lib -w assets -w test

# Different debounce timing (500ms)
flutter-w run -b 500

# Watch everything in src/ for reload, config files for restart
flutter-w run -w src/ -W "*.yaml" -W "*.json"

Environment Variables

  • FLUTTER_BIN: Override the Flutter executable path (default: flutter)
FLUTTER_BIN=/custom/path/to/flutter flutter-w run

Troubleshooting

Flutter command not found

Make sure Flutter is in your PATH:

export PATH="$PATH:/path/to/flutter/bin"

Permission denied

Make the script executable:

chmod +x ~/.pub-cache/bin/flutter-w

Hot reload not working

  • Ensure you're running in debug mode (not release)
  • Check that the files you're editing are in watched paths
  • Use -v flag for verbose logging to see what's being watched

License

MIT

Contributing

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

Author

Created to solve the issue of Flutter hot reload not working automatically in terminal/non-IDE environments, especially after dealing with CocoaPods installation issues on macOS.

Libraries