hotreloader 2.0.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 41

hotreloader (Dart) #

Build Status License Pub Package Contributor Covenant

  1. What is it?
  2. Requirements
  3. How to use
  4. Logging
  5. Alternatives
  6. Changelog / Version History
  7. License

What is it? #

This Dart library provides a code reloading service that monitors the local file system for changes to a Dart project's source files and automatically applies them using the Dart VM's hot reload capabilities to the running Dart process.

Requirements #

Dart SDK 2.6.0 or higher.

How to use #

  1. Add this to your pubspec.yml

    dev_dependencies:
      hotreloader: ^2.0.0
    
  2. Enable hot reloading in your entry point dart file, e.g. bin/main.dart

    import 'package:hotreloader/hotreloader.dart';
    
    Future<void> main(List<String> args) async {
    
      // instantiate a reloader that by default monitors the lib directory for source file changes
      final reloader = await HotReloader.create();
    
      // ... your other code
    
      // cleanup
      reloader.stop();
    }
    
  3. Run the dart program using the Dart VM with the --enable-vm-service flag enabled, e.g.

    dart --enable-vm-service bin/main.dart
    
  4. You can now change dart files under the lib and the changes should be applied to the running process.

The reloader service can be further customized, e.g.

import 'package:hotreloader/hotreloader.dart';

Future<void> main(List<String> args) async {

  final reloader = await HotReloader.create(
    debounceInterval: Duration(seconds: 2), // wait up to 2 seconds after file change before reloading
    onBeforeReload: (ctx) => //
      ctx.isolate.name != 'foobar' && // never reload the isolate named 'foobar'
      ctx.event?.path.contains('/mymodel/')) ?? true, // only perform reload when dart files under ../mymodel/ are changed
    onAfterReload: (ctx) => print('Hot-reload result: ${ctx.result}')
  );

  // ... your other code

  await reloader.reloadCode(); // programmatically trigger code reload

  // ... your other code

  // cleanup
  reloader.stop();
}

Logging #

This library uses the logging package for logging.

You can configure the logging framework and change the log-level programmatically like this:

import 'dart:io' as io;
import 'dart:isolate';
import 'package:hotreloader/hotreloader.dart';
import 'package:logging/logging.dart' as logging;

Future<void> main() async {
  logging.hierarchicalLoggingEnabled = true;
  // print log messages to stdout/stderr
  logging.Logger.root.onRecord.listen((msg) =>
    (msg.level < logging.Level.SEVERE ? io.stdout : io.stderr)
    .writeln('${msg.time} ${msg.level.name} [${Isolate.current.debugName}] ${msg.loggerName}: ${msg.message}')
  );


  HotReloader.logLevel = logging.Level.CONFIG;

  final reloader = await HotReloader.create();

  // ... your other code

  // cleanup
  reloader.stop();
}

Alternatives #

Changelog / Version History #

This project maintains a changelog and adheres to Semantic Versioning and Keep a CHANGELOG

License #

All files are released under the Apache License 2.0.

Changelog #

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased] #

[2.0.0] - 2020-04-09 #

Added #

  • watch dependencies for source code changes

Changed #

  • support slightly older versions of dependencies

[1.0.0] - 2020-04-08 #

  • initial release

example/README.md

hotreloader_example (Dart) #

  1. What is it?
  2. Requirements
  3. How to use
  4. License

What is it? #

Demo project for the hotreloader Dart library.

Requirements #

Dart SDK 2.6.0 or higher.

How to use #

Execute dart --enable-vm-service bin/main_dev.dart. This will start the demo application in development mode with hot code reload enabled:

Observatory listening on http://127.0.0.1:8181/8W0Tg0gOtFg=/
2020-04-09 12:33:53.877085 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\.packages] with [PollingFileWatcher]...
2020-04-09 12:33:53.883532 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\bin] with [WindowsDirectoryWatcher]...
2020-04-09 12:33:53.890973 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\dummylib_v1\lib] with [WindowsDirectoryWatcher]...
2020-04-09 12:33:53.891931 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\lib] with [WindowsDirectoryWatcher]...
2020-04-09 12:33:53.893419 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\test] with [PollingDirectoryWatcher]...
2020-04-09 12:33:53.897411 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\lib] with [WindowsDirectoryWatcher]...
getSystemInfo(): Date: 2020-04-09 12:33:54.900277 | Counter: 0 | Dummy Lib Version: v1
getSystemInfo(): Date: 2020-04-09 12:33:55.901058 | Counter: 1 | Dummy Lib Version: v1
...

Things to try out now:

  1. Change a source file of the example project.

    Open the file lib/src/utils.dart, modify the function getSystemInfo(), save the file and see the application reload automatically in the console.

     ...
     getSystemInfo(): Date: 2020-04-09 12:35:41.120626 | Counter: 14 | Dummy Lib Version: v1
     getSystemInfo(): Date: 2020-04-09 12:35:42.121742 | Counter: 15 | Dummy Lib Version: v1
     2020-04-09 12:35:42.134138 INFO [main] hotreloader: Change detected: type=[modify] path=[D:\dart-hotreloader\example\lib\src\utils.dart]
     2020-04-09 12:35:42.136124 INFO [main] hotreloader: Hot-reloading code...
     2020-04-09 12:35:42.582558 INFO [main] hotreloader: Hot-reloading code succeeded.
     getSystemInfo(): Date: 2020-04-09 12:35:43.124141 | Counter: 16 | Dummy Lib Version: v1 | Hello!!
     getSystemInfo(): Date: 2020-04-09 12:35:44.125226 | Counter: 17 | Dummy Lib Version: v1 | Hello!!
     ...
    
  2. Change a source file of a library referenced as dependency in the example project's pubspec.yaml.

    Open the file dummylib_v1/dummylib.dart, modify the function getVersion(), save the file and see the application reload automatically in the console.

     ...
     getSystemInfo(): Date: 2020-04-09 12:3/:29.174666 | Counter: 45 | Dummy Lib Version: v1 | Hello!!
     getSystemInfo(): Date: 2020-04-09 12:3/:30.178587 | Counter: 46 | Dummy Lib Version: v1 | Hello!!
     2020-04-09 12:37:30.701152 INFO [main] hotreloader: Change detected: type=[modify] path=[D:\dart-hotreloader\example\dummylib_v1\lib\dummylib.dart]
     2020-04-09 12:37:30.702641 INFO [main] hotreloader: Hot-reloading code...
     2020-04-09 12:37:31.158463 INFO [main] hotreloader: Hot-reloading code succeeded.
     getSystemInfo(): Date: 2020-04-09 12:37:31.181965 | Counter: 47 | Dummy Lib Version: v1-CHANGED! | Hello!!
     getSystemInfo(): Date: 2020-04-09 12:37:32.182957 | Counter: 48 | Dummy Lib Version: v1-CHANGED! | Hello!!
     getSystemInfo(): Date: 2020-04-09 12:37:33.186126 | Counter: 49 | Dummy Lib Version: v1-CHANGED! | Hello!!
     ...
    
  3. Change the version of a referenced library in the example project's pubspec.yaml.

    Open the pubspec.yaml and upgrade the version of the referenced dummylib package by changing the line path: ./dummylib_v1 to path: ./dummylib_v2.

    Then run the command pub get:

     D:\dart-hotreloader\example\> pub get
     Resolving dependencies...
     * dummylib 2.0.0 from path dummylib_v2 (was 1.0.0 from path dummylib_v1)
     Changed 1 dependency!
    
     ...
     getSystemInfo(): Date: 2020-04-09 12:39:33.357493 | Counter: 61 | Dummy Lib Version: v1-CHANGED! | Hello!!
     getSystemInfo(): Date: 2020-04-09 12:39:34.359268 | Counter: 62 | Dummy Lib Version: v1-CHANGED! | Hello!!
     2020-04-09 12:39:35.322030 INFO [main] hotreloader: Change detected: type=[modify] path=[D:\dart-hotreloader\example\.packages]
     2020-04-09 12:39:35.323533 INFO [main] hotreloader: Hot-reloading code...
     getSystemInfo(): Date: 2020-04-09 12:39:35.763598 | Counter: 63 | Dummy Lib Version: v2 | Hello!!
     2020-04-09 12:39:35.768549 INFO [main] hotreloader: Stopping to watch paths...
     2020-04-09 12:39:35.780544 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\.packages] with [PollingFileWatcher]...
     2020-04-09 12:39:35.783024 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\bin] with [WindowsDirectoryWatcher]...
     2020-04-09 12:39:35.786528 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\dummylib_v2\lib] with [WindowsDirectoryWatcher]...
     2020-04-09 12:39:35.788016 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\lib] with [WindowsDirectoryWatcher]...
     2020-04-09 12:39:35.789504 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\example\test] with [PollingDirectoryWatcher]...
     2020-04-09 12:39:35.791488 CONFIG [main] hotreloader: Watching [D:\dart-hotreloader\lib] with [WindowsDirectoryWatcher]...
     2020-04-09 12:39:35.792892 INFO [main] hotreloader: Hot-reloading code succeeded.
     getSystemInfo(): Date: 2020-04-09 12:39:36.766006 | Counter: 64 | Dummy Lib Version: v2 | Hello!!
     getSystemInfo(): Date: 2020-04-09 12:39:37.768430 | Counter: 65 | Dummy Lib Version: v2 | Hello!!
     ...
    

License #

All files are released under the Apache License 2.0.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  hotreloader: ^2.0.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:hotreloader/hotreloader.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
2
Health:
Code health derived from static analysis. [more]
81
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
80
Overall:
Weighted score of the above. [more]
41
Learn more about scoring.

We analyzed this package on Jul 7, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.13

Analysis suggestions

Package not compatible with runtime flutter-web on web

Because of the import of dart:io via the import chain package:hotreloader/hotreloader.dartpackage:hotreloader/src/util/vm.dartpackage:vm_service/vm_service_io.dartdart:io

Package not compatible with runtime web

Because of the import of dart:io via the import chain package:hotreloader/hotreloader.dartpackage:hotreloader/src/util/vm.dartpackage:vm_service/vm_service_io.dartdart:io

Health suggestions

Fix lib/hotreloader.dart. (-13.09 points)

Analysis of lib/hotreloader.dart reported 28 hints, including:

line 1 col 1: Prefer using /// for doc comments.

line 25 col 14: Unnecessary new keyword.

line 28 col 3: Prefer using /// for doc comments.

line 33 col 3: Prefer using /// for doc comments.

line 38 col 3: Prefer using /// for doc comments.

Fix lib/src/util/docker.dart. (-1.49 points)

Analysis of lib/src/util/docker.dart reported 3 hints:

line 1 col 1: Prefer using /// for doc comments.

line 12 col 1: Prefer using /// for doc comments.

line 17 col 20: Unnecessary new keyword.

Fix lib/src/util/pub.dart. (-1.49 points)

Analysis of lib/src/util/pub.dart reported 3 hints:

line 1 col 1: Prefer using /// for doc comments.

line 16 col 21: Unnecessary new keyword.

line 31 col 20: Unnecessary new keyword.

Fix additional 4 files with analysis or formatting issues. (-3.49 points)

Additional issues in the following files:

  • lib/src/util/vm.dart (3 hints)
  • lib/src/util/files.dart (2 hints)
  • lib/src/util/iterables.dart (1 hint)
  • lib/src/util/strings.dart (1 hint)

Maintenance suggestions

The package description is too short. (-20 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.6.0 <3.0.0
logging ^0.11.3+2 0.11.4
path ^1.6.3 1.7.0
stream_transform ^1.0.0 1.2.0
vm_service ^4.0.0 4.1.0
watcher ^0.9.7+10 0.9.7+15
Transitive dependencies
async 2.4.2
collection 1.14.13
meta 1.2.1
pedantic 1.9.1
Dev dependencies
lint ^1.0.0