Flutter Auto Hot Reload

This skill provides guidance for setting up automatic hot reload in Flutter projects, enabling instant UI updates when code changes without manual intervention.

Overview

Flutter's hot reload injects updated source code into the running Dart VM, preserving app state while showing changes instantly. By default, terminal-based workflows require manually pressing 'r' after each change. This skill enables automatic hot reload across different development environments.

Terminal-Based Workflows (Claude Code, vim, etc.)

Method 1: PID File + File Watcher (Recommended)

Start Flutter with the --pid-file flag to enable signal-based hot reload:

# Start Flutter with PID tracking
flutter run -d chrome --pid-file=/tmp/flutter.pid
flutter run -d iPhone --pid-file=/tmp/flutter.pid
flutter run -d emulator-5554 --pid-file=/tmp/flutter.pid

Then use a file watcher to trigger reload on changes:

Using fswatch (macOS):

# Install if needed
brew install fswatch

# Watch lib/ and trigger hot reload on changes
fswatch -o lib/ | xargs -n1 -I{} kill -USR1 $(cat /tmp/flutter.pid)

Using entr (cross-platform):

# Install if needed
brew install entr  # macOS
apt install entr   # Linux

# Watch and reload
find lib -name '*.dart' | entr -p kill -USR1 $(cat /tmp/flutter.pid)

Using inotifywait (Linux):

while inotifywait -r -e modify lib/; do
  kill -USR1 $(cat /tmp/flutter.pid)
done

Signal Reference

Signal	Action	Use Case
SIGUSR1	Hot Reload	Dart file changes
SIGUSR2	Hot Restart	pubspec.yaml, asset changes

Method 2: flutter_hot_reload Package

Install the CLI wrapper that handles file watching automatically:

dart pub global activate flutter_hot_reload

Run instead of flutter run:

flutter_hot_reload -d chrome
flutter_hot_reload -d iPhone

Features:

• Watches .dart files automatically
• Hot restarts on pubspec.yaml changes
• Works with any editor or terminal
• No IDE plugin required

Method 3: Web Experimental Hot Reload (Flutter 3.32+)

For web development specifically:

flutter run -d chrome --web-experimental-hot-reload

This enables automatic hot reload for web without additional setup.

Chrome DevTools MCP Integration

When using Chrome DevTools MCP to interact with Flutter web apps, use web-server mode instead of -d chrome to avoid conflicts.

The Problem

Running flutter run -d chrome opens its own Chrome instance. If you also have Chrome DevTools MCP connected to a separate Chrome viewing the same app, you'll get GlobalKey conflicts:

A GlobalKey was used multiple times inside one widget's child list.
The offending GlobalKey was: [LabeledGlobalKey<NavigatorState>]

This happens because both Chrome instances are running the same Flutter app simultaneously.

The Solution: Web Server Mode

Start Flutter as a web server without opening a browser:

# Start Flutter web server only (no browser opens)
flutter run -d web-server --web-port=61060 --pid-file=/tmp/flutter.pid

Then navigate your MCP Chrome to the app:

• URL: http://localhost:61060

Hot Reload with Web Server Mode

Hot reload signals still work with web-server mode:

# Hot reload
kill -USR1 $(cat /tmp/flutter.pid)

# Hot restart
kill -USR2 $(cat /tmp/flutter.pid)

After sending the signal, refresh the MCP Chrome page to see the changes (the web server recompiles, but the browser needs to reload).

Quick Setup for MCP

# Terminal 1: Start Flutter web server
flutter run -d web-server --web-port=61060 --pid-file=/tmp/flutter.pid

# Then use Chrome DevTools MCP to navigate to http://localhost:61060
# Hot reload with: kill -USR1 $(cat /tmp/flutter.pid)

Note: Unlike -d chrome mode where hot reload updates instantly, with web-server + MCP you may need to refresh the browser after triggering reload.

Multi-Device Auto Reload

Run multiple devices simultaneously with auto-reload for all:

# Terminal 1: iOS Simulator
flutter run -d iPhone --pid-file=/tmp/flutter-ios.pid

# Terminal 2: Android Emulator
flutter run -d emulator-5554 --pid-file=/tmp/flutter-android.pid

# Terminal 3: Chrome
flutter run -d chrome --pid-file=/tmp/flutter-web.pid

# Terminal 4: Watcher (reloads ALL devices)
fswatch -o lib/ | xargs -n1 -I{} sh -c 'kill -USR1 $(cat /tmp/flutter-ios.pid) $(cat /tmp/flutter-android.pid) $(cat /tmp/flutter-web.pid) 2>/dev/null'

VS Code Setup

VS Code with the Flutter extension supports auto hot reload natively:

1. Open Settings (Cmd+,)
2. Search "Flutter Hot Reload On Save"
3. Set to one of:
   • manual - Only on manual save (Cmd+S)
   • all - On manual save and autosave
   • allDirty - When file has unsaved changes
   • manualDirty - Manual save only if changes exist

Recommended setting for autosave users:

{
  "dart.flutterHotReloadOnSave": "all"
}

Android Studio / IntelliJ Setup

1. Open Settings > Tools > Actions on Save
2. Enable "Save files if IDE is idle for X seconds" (recommend 2 seconds)
3. Open Settings > Languages & Frameworks > Flutter
4. Check "Perform hot reload on save"

Convenience Script

Use the bundled script for easy setup:

# From skill directory
~/.claude/skills/flutter-auto-reload/scripts/flutter-watch.sh -d chrome
~/.claude/skills/flutter-auto-reload/scripts/flutter-watch.sh -d iPhone

Troubleshooting

Hot Reload Not Triggering

1. Verify PID file exists: cat /tmp/flutter.pid
2. Verify process is running: ps -p $(cat /tmp/flutter.pid)
3. Check file watcher is running and watching correct directory
4. Ensure changes are in lib/ directory (not test/ or other)

Hot Reload vs Hot Restart

Some changes require hot restart (SIGUSR2) instead of reload:

• Changes to main() function
• Changes to global/static variables initialization
• Changes to native code
• Asset changes
• pubspec.yaml changes

State Not Preserved

Hot reload preserves state, but if state is lost:

• Check for errors in console
• Ensure no syntax errors in changed files
• Try hot restart if reload fails silently

Quick Reference

Environment	Command
Terminal + fswatch	fswatch -o lib/ | xargs -n1 -I{} kill -USR1 $(cat /tmp/flutter.pid)
Terminal + entr	find lib -name '*.dart' | entr -p kill -USR1 $(cat /tmp/flutter.pid)
flutter_hot_reload	flutter_hot_reload -d <device>
Web experimental	flutter run -d chrome --web-experimental-hot-reload
VS Code	Set dart.flutterHotReloadOnSave to all
Android Studio	Enable in Settings > Flutter > Hot reload on save

Resources

• Flutter Hot Reload Documentation
• flutter_hot_reload Package
• Flutter Auto-Reload for Terminal Workflows