|
| 1 | +<h1 align="center">AppRunner</h1> |
| 2 | + |
| 3 | +<a href="https://madbrains.ru/"><img src="https://firebasestorage.googleapis.com/v0/b/mad-brains-web.appspot.com/o/logo.png?alt=media" width="200" align="right" style="margin: 20px;"/></a> |
| 4 | + |
| 5 | +[](https://pub.dartlang.org/packages/app_runner) |
| 6 | +[](https://opensource.org/licenses/MIT) |
| 7 | + |
| 8 | +Launch your Flutter app like a pro! AppRunner is a configurator for quick and controlled launch of your application, with features that runApp does not have. |
| 9 | + |
| 10 | +## Features |
| 11 | +* Get your application up and running quickly. |
| 12 | +* Allows you to run code without blocking your application from launching. |
| 13 | +* Show your independent splash screen while loading the app. AppRunner does not block the first call of the widget, do you practically won't see the native splash screen. |
| 14 | +* Allows you to reload the widget tree if you need it. |
| 15 | +* Your code will run in a safe environment for both Dart code and Flutter code. AppRunner catches and handles errors, preventing your application from breaking at runtime. |
| 16 | +* Configuring the zone of your application is much easier. |
| 17 | +* With AppRunner you can easily override ErrorWidget for debug and release mode. |
| 18 | +* Lets you just use your WidgetsBinding implementation. |
| 19 | +* And the very last and most important argument to use AppRunner in your application, it is very easy to integrate into your application, and its configuration does not take much time. |
| 20 | + |
| 21 | +<table> |
| 22 | + <tr> |
| 23 | + <td>Splash Screen</td> |
| 24 | + <td>Debug Error Screen</td> |
| 25 | + <td>Release Error Screen</td> |
| 26 | + </tr> |
| 27 | + <tr> |
| 28 | + <td><img src="docs/assets/run.gif" width=200 height=400 alt="run" /></td> |
| 29 | + <td><img src="docs/assets/debug-error.jpg" width=200 height=400 alt="debug-error" /></td> |
| 30 | + <td><img src="docs/assets/release-error.jpg" width=200 height=400 alt="release-error" /></td> |
| 31 | + </tr> |
| 32 | +</table> |
| 33 | + |
| 34 | +## Installing |
| 35 | +Add this to your package's `pubspec.yaml` file: |
| 36 | +```yaml |
| 37 | +dependencies: |
| 38 | + app_runner: 1.0.0 |
| 39 | +``` |
| 40 | +
|
| 41 | +## Usage |
| 42 | +
|
| 43 | +This is how your application launch looked like before: |
| 44 | +```dart |
| 45 | +import 'package:flutter/material.dart'; |
| 46 | + |
| 47 | +void main() { |
| 48 | + runApp(MyApp()); |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +It is simply by attaching your widget to the root. But in order to catch errors, it was necessary to use runZonedGuarded, then our code will become like this: |
| 53 | +```dart |
| 54 | +import 'dart:async'; |
| 55 | +
|
| 56 | +import 'package:flutter/material.dart'; |
| 57 | +
|
| 58 | +void main() { |
| 59 | + runZonedGuarded<void>( |
| 60 | + () { |
| 61 | + runApp(MyApp()); |
| 62 | + }, |
| 63 | + (Object error, StackTrace stackTrace) {...}, |
| 64 | + zoneValues: ..., |
| 65 | + zoneSpecification: ..., |
| 66 | + ); |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +But we also need to initialize some code to launch the application, for example Firebase: |
| 71 | +```dart |
| 72 | +import 'dart:async'; |
| 73 | +
|
| 74 | +import 'package:flutter/material.dart'; |
| 75 | +void main() { |
| 76 | + runZonedGuarded<void>( |
| 77 | + () async { |
| 78 | + WidgetsFlutterBinding.ensureInitialized(); |
| 79 | +
|
| 80 | + await Firebase.initializeApp(); |
| 81 | +
|
| 82 | + HydratedBloc.storage = await HydratedStorage.build( |
| 83 | + storageDirectory: await getApplicationDocumentsDirectory(), |
| 84 | + ); |
| 85 | +
|
| 86 | + Bloc.observer = MyBlocObserver(); |
| 87 | +
|
| 88 | + runApp(MyApp()); |
| 89 | + }, |
| 90 | + (Object error, StackTrace stackTrace) {}, |
| 91 | + zoneValues: ..., |
| 92 | + zoneSpecification: ..., |
| 93 | + ); |
| 94 | +} |
| 95 | +``` |
| 96 | + |
| 97 | +And what do we have: |
| 98 | +* The launch of the widget is blocked by the third-party code. |
| 99 | +* The splash screen is implemented in MyApp, that is, it will be present in the tree when it is no longer needed. |
| 100 | +* Not the most beautiful and understandable code. |
| 101 | + |
| 102 | +Let's fix this with AppRunner (all possible parameters are shown here, it is not necessary to use all of them): |
| 103 | +```dart |
| 104 | +import 'package:app_runner/app_runner.dart'; |
| 105 | +import 'package:flutter/material.dart'; |
| 106 | +
|
| 107 | +void main() { |
| 108 | + appRunner( |
| 109 | + RunnerConfiguration( |
| 110 | + widgetConfig: WidgetConfiguration( |
| 111 | + app: MyApp(), // Our application |
| 112 | + splash: const Splash(), // Our splash screen |
| 113 | + errorBuilder: (BuildContext context, FlutterErrorDetails errorDetails) => MyErrorScreen(errorDetails), // Our flutter error screen during debugging |
| 114 | + releaseErrorBuilder: (BuildContext context) => MyReleaseErrorScreen(), // Our flutter error screen during release |
| 115 | + onFlutterError: (FlutterErrorDetails errorDetails) { |
| 116 | + // Flutter error handling |
| 117 | + dev.log(errorDetails.toString(), |
| 118 | + name: 'onFlutterError', stackTrace: errorDetails.stack); |
| 119 | + }, |
| 120 | + initializeBinding: () => CustomWidgetsFlutterBinding(), // Creating your WidgetsFlutterBinding |
| 121 | + ), |
| 122 | + zoneConfig: ZoneConfiguration( |
| 123 | + onZoneError: (Object error, StackTrace stackTrace) { |
| 124 | + // Dart error handling |
| 125 | + dev.log(error.toString(), |
| 126 | + name: 'onZoneError', stackTrace: stackTrace); |
| 127 | + }, |
| 128 | + zoneValues: ..., // Your zone parameters |
| 129 | + zoneSpecification: ..., // Your zone specifications |
| 130 | + ), |
| 131 | + preInitializeFunctions: (WidgetsBinding binding) async { |
| 132 | + // Custom code initialization. |
| 133 | + // You don't need to call WidgetsFlutterBinding.ensureInitialized(); |
| 134 | + // WidgetsBinding is also available here if you need it. |
| 135 | +
|
| 136 | + await Firebase.initializeApp(); |
| 137 | +
|
| 138 | + HydratedBloc.storage = await HydratedStorage.build( |
| 139 | + storageDirectory: await getApplicationDocumentsDirectory(), |
| 140 | + ); |
| 141 | +
|
| 142 | + Bloc.observer = MyBlocObserver(); |
| 143 | + }, |
| 144 | + ), |
| 145 | + ); |
| 146 | +} |
| 147 | +``` |
| 148 | + |
| 149 | +If you need to reload the widgets, you can do: |
| 150 | +```dart |
| 151 | +reloadWidget(context); |
| 152 | +
|
| 153 | +// or |
| 154 | +
|
| 155 | +context.reloadWidget(); |
| 156 | +``` |
| 157 | + |
| 158 | +## Example |
| 159 | +The [Example][example] is in the corresponding folder |
| 160 | + |
| 161 | +[example]: https://github.com/MadBrains/App-Runner-Flutter/tree/main/example/ |
0 commit comments