Utopia Hot Reload #

Advanced hot reload and hot restart functionality for Dart applications with true VM-based hot reload capabilities, similar to Flutter's development experience.

Features #

🔥 True Hot Reload: Uses Dart VM service to reload code while preserving application state (like Flutter)
🔄 Hot Restart: Full process restart when hot reload isn't possible
🚀 Auto Mode: Intelligently tries hot reload first, falls back to restart
⌨️ Flutter-like Commands: 'r' for hot reload, 'R' for hot restart, 'q' to quit
📁 File Watching: Configurable paths and extensions with debouncing
🎯 Smart Fallback: Graceful error handling with automatic mode switching

Installation #

dev_dependencies:
  utopia_hotreload: ^1.0.0

Quick Start #

import 'dart:io';
import 'package:utopia_hotreload/utopia_hotreload.dart';

void main() async {
  await DeveloperTools.start(
    script: () async {
      // Your application code here
      final server = await HttpServer.bind('127.0.0.1', 8080);
      print('🚀 Server running on http://127.0.0.1:8080');
      
      await for (final request in server) {
        request.response
          ..write('Hello from hot reload! Time: ${DateTime.now()}')
          ..close();
      }
    },
    watchPaths: ['lib', 'bin'],
    watchExtensions: ['.dart'],
  );
}

Usage #

Basic Usage #

The API is designed to be simple and Flutter-like:

import 'package:utopia_hotreload/utopia_hotreload.dart';

void main() async {
  await DeveloperTools.start(
    script: () async {
      // Your application code here
    },
  );
}

With Utopia HTTP #

import 'dart:io';
import 'package:utopia_http/utopia_http.dart';
import 'package:utopia_hotreload/utopia_hotreload.dart';

void main() async {
  await DeveloperTools.start(
    script: () async {
      final app = Http(ShelfServer(InternetAddress.anyIPv4, 8080));
      
      app.get('/').inject('response').action((Response response) {
        response.text('Hello with hot reload! 🔥');
        return response;
      });
      
      await app.start();
    },
    watchPaths: ['lib', 'example'],
    watchExtensions: ['.dart'],
  );
}

Advanced Configuration #

await DeveloperTools.start(
  script: () async {
    // Your server code
  },
  watchPaths: ['lib', 'bin', 'web'],
  watchExtensions: ['.dart', '.yaml'],
  ignorePatterns: ['**/.dart_tool/**', '**/build/**'],
  debounceDelay: Duration(milliseconds: 300),
  verbose: true,
);

Flutter-like Development Experience #

When you run your application, you'll see:

🔥 Hot reload enabled. Press:
  r + Enter: Hot reload
  R + Enter: Hot restart  
  q + Enter: Quit

🚀 Starting application with auto hot reload...
📁 Watching paths: [lib, bin]
📄 Watching extensions: [.dart]

💡 Commands available:
  r + Enter: Hot reload (preserves state)
  R + Enter: Hot restart (full restart)  
  q + Enter: Quit

🌐 Server running on http://127.0.0.1:8080

Commands #

r + Enter: Hot reload - Preserves application state, faster
R + Enter: Hot restart - Full application restart, more reliable
q + Enter: Quit the development server

Auto Mode Behavior #

The package always uses auto mode (like Flutter), which:

Tries hot reload first - Attempts to preserve state using Dart VM service
Falls back to hot restart - If hot reload fails or isn't available
Provides feedback - Shows which mode was used and why

How It Works #

True Hot Reload ✨ #

Uses Dart VM Service's reloadSources() API - Updates code in the running process
Preserves application state - Variables, connections, and server instances remain intact
Same port, same PID - Server continues running without interruption
Requires --enable-vm-service flag - Automatically enabled by the package
Similar to Flutter's hot reload - Instant code updates with state preservation

Hot Restart 🔄 #

Terminates and restarts the entire Dart process - Fresh compilation and clean state
Loses all application state - Variables reset, connections closed, new server instance
New port, new PID - Complete process restart
More compatible across different scenarios - Guaranteed to pick up all code changes
Used as fallback - When hot reload fails or for structural changes

Automatic Fallback #

The package intelligently chooses the best reload method:

📝 File changed: lib/server.dart
🔥 Performing true hot reload...
✅ Hot reload completed - code updated in running process!

For structural changes that can't be hot reloaded:

📝 File changed: lib/server.dart
🔥 Performing true hot reload...
❌ Hot reload failed: Structural changes detected
🔄 Hot reload not available, performing hot restart...
🔄 Performing true hot restart (restarting entire process)...
✅ Hot restart completed

Configuration Options #

`DeveloperTools.start()` Parameters #

Parameter	Type	Default	Description
`script`	`Function`	required	Your application entry point
`watchPaths`	`List<String>`	`['lib']`	Directories to watch for changes
`watchExtensions`	`List<String>`	`['.dart']`	File extensions to monitor
`ignorePatterns`	`List<String>`	See below	Patterns to ignore
`debounceDelay`	`Duration`	`500ms`	Delay before triggering reload
`verbose`	`bool`	`false`	Enable detailed logging

Default Ignore Patterns #

[
  '.git/',
  '.dart_tool/',
  'build/',
  'test/',
  '.packages',
  'pubspec.lock',
  '.vscode/',
  '.idea/',
  '*.log',
  '*.tmp',
]

Examples #

Simple HTTP Server #

import 'dart:io';
import 'package:utopia_hotreload/utopia_hotreload.dart';

void main() async {
  await DeveloperTools.start(
    script: () async {
      final server = await HttpServer.bind('127.0.0.1', 8080);
      
      await for (final request in server) {
        request.response
          ..headers.contentType = ContentType.html
          ..write('''
            <h1>Hot Reload Demo</h1>
            <p>Time: ${DateTime.now()}</p>
            <p>Try editing this file!</p>
          ''')
          ..close();
      }
    },
  );
}

Console Application #

import 'dart:io';
import 'package:utopia_hotreload/utopia_hotreload.dart';

void main() async {
  await DeveloperTools.start(
    script: () async {
      print('🚀 Console app with hot reload');
      print('Current time: ${DateTime.now()}');
      
      // Keep running
      await stdin.first;
    },
    verbose: true,
  );
}

Migration from HttpDev #

If you were using HttpDev from utopia_http:

Before (HttpDev) #

import 'package:utopia_http/utopia_http.dart';

void main() async {
  await HttpDev.start(
    script: () => runServer(),
    watchPaths: ['lib'],
  );
}

After (DeveloperTools) #

import 'package:utopia_hotreload/utopia_hotreload.dart';

void main() async {
  await DeveloperTools.start(
    script: () => runServer(),
    watchPaths: ['lib'],
  );
}

Requirements #

Dart SDK 2.17.0 or higher
For hot reload: Dart VM service support (automatically enabled)

Troubleshooting #

Hot Reload Not Working #

If hot reload consistently fails:

Check for structural changes - Hot reload can't handle class/method signature changes
Use hot restart - Press R + Enter for structural changes
Enable verbose mode - Set verbose: true to see detailed error messages

File Changes Not Detected #

Check watch paths - Ensure your files are in the specified watchPaths
Check extensions - Make sure file extensions are in watchExtensions
Check ignore patterns - Verify files aren't excluded by ignorePatterns

Performance Issues #

Reduce watch scope - Watch only necessary directories
Increase debounce delay - Set higher debounceDelay for slower systems
Add ignore patterns - Exclude large directories like node_modules

Advanced Usage #

Custom Error Handling #

The auto mode provides automatic fallback, but you can also handle specific scenarios:

await DeveloperTools.start(
  script: () async {
    try {
      // Your application code
    } catch (e) {
      print('Application error: $e');
      // Handle gracefully
    }
  },
  verbose: true, // See detailed reload information
);

Multiple File Types #

await DeveloperTools.start(
  script: () => runServer(),
  watchPaths: ['lib', 'web', 'config'],
  watchExtensions: ['.dart', '.yaml', '.json'],
);

License #

MIT License - see LICENSE file for details.

utopia_hotreload 1.0.0 utopia_hotreload: ^1.0.0 copied to clipboard

Metadata