Navigate and prosper 🖖
Router, requirements & dependency injection library for Flutter.
If your app is a list of screens with respective paths then this library is for you.
- YAML/JSON based Navigation Spec
- support for query parameters
- support for global parameters
- path subsections
- parameters interpolation in subsections
- logicless
- deliverable over the air (think Firebase remote config)
- code generator for paths/tests/plugins
- schema validation (draft v7)
- Highly customizable plugin architecture.
- VoyagerWidget to embed your
pathat any point - Provider to inject any data coming with the
path - Works with Flutter Web
To use this plugin, add voyager as a dependency in your pubspec.yaml file.
You should ensure that you add the router as a dependency in your flutter project.
dependencies:
voyager: ^latest_release
provider: ^3.0.0+1 # if you don't have it yetYou can also reference the git repo directly if you want:
dependencies:
voyager:
git: git://github.com/vishna/voyager.gitThen in the code, make sure you import voyager package:
/// prevent name clash with upcoming Flutter's Router class using hide
import 'package:voyager/voyager.dart' hide Router;
import 'package:voyager/voyager.dart' as voyager;It’s best to start with describing what paths your app will have and what subsections will they be made of.
---
'/home' :
type: 'home'
widget: HomeWidget
title: "This is Home"
'/other/:title' :
type: 'other'
widget: OtherWidget
title: "This is %{title}"You can either put this in assets as a yaml file or use triple quotes ''' and keep it in your code as a string. The String approach while a bit uglier allows for faster reloads while updating assets requires project rebuild.
Your router requires paths and plugins as constructor parameters. Getting paths is quite straightforwad and basically means parsing that YAML file we just defined.
final paths = loadPathsFromString('''
---
'/home' :
type: 'home'
widget: HomeWidget
title: "This is Home"
'/other/:title' :
type: 'other'
widget: OtherWidget
title: "This is %{title}"
''');or if the file is in the assets folder, you can:
final paths = loadPathsFromAssets("assets/navigation.yml");NOTE: JSON support is available as of version 0.2.3, please check voyager_test.dart for reference.
The other important ingredient of voyager router are plugins. You need to tell router what kind of plugins you plan to use and those depend on what you have written in the navigation file. In our example we use 2 widget and title. This library comes with predefined plugins for widget and in the next paragraph you can read how to create your own plugin for title.
final plugins = [
WidgetPluginBuilder() /// provide widget builders for expressions used in YAML
.add<HomeWidget>((context) => HomeWidget())
.add<OtherWidget>((context) => OtherWidget())
.build(),
TitlePlugin() /// custom plugin
];Now you're all set for getting your router instance:
Future<voyager.Router> router = loadRouter(paths, plugins)You can define as many plugins as you want. Here's how you could handle the title nodes from the example navigation yaml.
class TitlePlugin extends RouterPlugin {
TitlePlugin() : super("title"); // YAML node to intercept
@override
void outputFor(RouterContext context, dynamic config, Voyager voyager) {
// config can be anything that is passed from YAML
voyager["title"] = config.toString(); // output of this plugin
}
}NOTE: Above plugin is redundant, Voyager will repackage the primitive types from configuration and you don't need to do anything 😎 Use plugins to resolve primitive types to custom types , e.g. take a look at IconPlugin from the example app.
Voyager instance is the composite output of all the relevant plugins that are nested under the path being resolved. Observe:
Voyager voyager = router.find("/home")
print(voyager["title"]); /// originates from the title plugin, prints: "This is home"
print(voyager["type"]); /// automatically inherited from the YAML map
print(voyager.type); /// strong typed type
assert(voyager["widget"] is WidgetBuilder); /// originates from the widget pluginNOTE: Any attempt to modify voyager keys will fail unless done from plugin's outputFor method. If you want to add some values to Voyager later on, use Voyager.storage public map.
NOTE: Planning on using Voyager with Flutter web? Keep in mind that class names in release mode are getting obfuscated by dart2js. Currently the workaround for this is to provide obfuscation map yourself before registering any plugins:
VoyagerUtils.addObfuscationMap({
HomeWidget: "HomeWidget",
OtherWidget: "OtherWidget"
});Failure to provide obfuscation map might result in grey screen of death.
If your path uses widget plugin you can try using VoyagerWidget and embed any path you want like this:
VoyagerWidget(path: "/home", router: router);RECOMMENDED: Provide router at the top of your widget tree and omit passing router parameter.
If you use VoyagerWidget to create screens for your paths, you can obtain Voyager anywhere from BuildContext using extension getter (that is using Provider underneath):
final voyager = context.voyager;Now going back to our mystery OtherWidget class from the example navigation spec, that widget could be implemented something like this:
class OtherWidget extends StatelessWidget {
@override
Widget build(BuildContext context) {
final voyager = context.voyager; // injecting voyager from build context
final title = voyager["title"];
return Scaffold(
appBar: AppBar(
title: Text(title), // et voilà
),
body: Center(
child: Text("Other Page"),
)
);
}
}Defining inital path & handling navigation
final initalPath = "/my/fancy/super/path"
Provider<voyager.Router>.value(
value: router,
child: MaterialApp(
home: VoyagerWidget(path: initalPath),
onGenerateRoute: router.generator()
)
)Make sure you wrap your app with router provider.
NOTE: You can use MaterialApp.initalRoute but please read this first if you find MaterialApp.initalRoute is not working for you. TL;DR: It's working as intended ¯\_(ツ)_/¯
Having BuildContext and Material.onGenerateRoute set up, you can simply:
Navigator.of(context).pushNamed("/path/to/go");If you need to push new screen from elsewhere you probably should set navigatorKey to your MaterialApp
The article "Create Custom Router Transition in Flutter using PageRouteBuilder" by Agung Surya explains in detail how to create custom reusable transtions.
Essentially you need to extend a PageRouteBuilder class and pass it a widget you want to be transitioning to. In our case that widget is a VoyagerWidget.
In the aforementioned artile, the author created SlideRightRoute transition. We can combine that transition with any path from our navigation spec by using code below:
Navigator.push(
context,
SlideRightRoute(widget: VoyagerWidget.fromPath(context, "/path/to/go")),
);If you want to expose some global parameters to specs interpolation, you can do so by doing the following:
router.registerGlobalParam("isTablet", false);NOTE: Because we interpolate String here, only primitve types are allowed.
If you want to make some global entities available via router instance, you can do so by doing the following:
router.registerGlobalEntity("database", someDatabase);
Check out full example here
IMPORTANT: Code generation relies heavily on the type value. It should be unique per path definition, also the values should_be_snake_case
Voyager supports generating dart code based on the configuration yaml file. Simply run the following command and wait for the script to set it up for you.
flutter packages pub run voyager:codegen
This should create a voyager-codegen.yaml file in a root of your project, like so:
- name: Voyager # base name for generated classes, e.g. VoyagerData, VoyagerTests etc.
source: assets/navigation.yaml
target: lib/gen/voyager_gen.dartWhenever you edit the voyager-codegen.yaml or source file the code generation logic will pick it up (as long as pub run is running) and generate new dart souces to the target location.
CODE FORMATTING: If you want to have Flutter's default code formatting, make sure you have dart-sdk in you PATH, it's included with flutter sdk, so you can e.g.:
export PATH="$PATH:/path/to/flutter/bin/cache/dart-sdk/bin"
Proper formatting relies on dartfmt command being available.
NOTE 1: For code generator implementation details please check the source code at vishna/voyager-codegen.
NOTE 2: Should you want run code generation only once (and not watch files continously) you can supply additional --run-once flag to pub run command:
flutter packages pub run voyager:codegen --run-once
This can be useful if running in a CI/CD context.
NOTE 3: You might want to add .jarCache/ to your .gitignore to avoid checking in binary jars to your repo.
NOTE 4: If you're a Windows user make sure you have wget installed.
Typing navigation paths by hand is error prone, for this very reason it is recommended to use code generator for the paths, so rather than typing:
Navigator.of(context).pushNamed("/other/thingy");you can rely on your IDE's autocompletion and do this:
Navigator.of(context).pushNamed(pathOther("thingy"));Add your validation in voyager-codegen.yaml, for instance to cover IconPlugin you can now do this:
- name: Voyager
source: lib/main.dart
target: lib/gen/voyager_gen.dart
schema:
icon:
pluginStub: true # add if you want to generate aplugin stub
output: Icon # associated Dart class produced by the plugin
import: "package:flutter/widgets.dart" # Dart import for the output class, if necessary
input: # write schema for your the icon node (JSON Schema draft-07 layout)
type: string
pattern: "^[a-fA-F0-9]{4}$"Now whenever you run voyager:codegen you'll get an extra message stating all is fine:
✅ Schema validated properly
...or an error specific to your router configuration map, e.g.:
🚨 /fab@icon: #/icon: string [e88fd] does not match pattern ^[a-fA-F0-9]{4}$
Furthermore you gain strong typed reference to the plugin output in extended Voyager instance:
assert(voyager.icon is Icon);Finally, pluginStub: true gets you an abstract plugin class, so that you can avoid typing voyager["node_name"] manually. Just focus on parsing the node's config input and converting it into an expected output:
class IconPlugin extends IconPluginStub {
@override
Icon buildObject(RouterContext context, dynamic config) {
/// write your code here
}
}
If you want to try this feature out, your voyager-codegen.yaml should look something like that:
- name: Voyager
source: assets/navigation.yaml
target: lib/gen/voyager_gen.dart
testTarget: test/gen/voyager_test_scenarios.darttestTarget points to where the generated test code should go.
Say your regular test file is located in the test directory, this is how you could integrate with the generated code:
import 'gen/voyager_test_scenarios.dart';
/// override abstract base class with all the scenarios to test
class TestScenarios extends VoyagerTestScenarios {
/// default wrapper for all the widgets
MyVoyagerScenarios() : super((widget) => MaterialApp(home: widget));
@override
/// example scenario implementation for the `/home` path
List<VoyagerTestHomeScenario> homeScenarios() {
return [
VoyagerTestHomeScenario.write((tester) async {
expect(find.text("Home Page"), findsOneWidget);
})
];
}
/// etc...
}
void main() {
/// finally invoke tests, you need to suply `router` as `Future<Router>`
voyagerAutomatedTests("voyager auto tests", router, TestScenarios());
}Full code available at example/test/widget_test.dart.
voyagerAutomatedTests comes with a positional argument forceTests set to true by default. This will assert every widget has at least one scenario written for it, otherwise your tests will fail. Set it to false to disable this behaviour.
The scenario code is by default being executed within WidgetTester's runAsync meaning you should be able to perform real asynchronous methods.
The router is loaded every time the scenario is running - if this is something you don't need consider using e.g. AsyncMemoizer
- fluro As their repo says: "The brightest, hippest, coolest router for Flutter." Probably the most know flutter router out there.
- angel-route "A powerful, isomorphic routing library for Dart." Voyager internally was depending on this library till version
0.2.3. It was a server oriented library and too big dependency for this project - voyager is now using abstract_router.dart which is < 300 LOC. - eyeem/router Protoplast of the voyager library, written in Java, for Android.
- NASA Voyager 2 Interstellar Poster Beautiful artwork I found on NASA page also a base content for the banner - changed colors to flutter ones, cropped the poster, added flutter antenna.