zenrouter 3.0.0-beta.1

zenrouter: ^3.0.0-beta.1 copied to clipboard

Type-safe navigation for Flutter apps.

Define each screen as a type and compose routes as a graph. That gives you type-safe navigation, deep linking, browser back-button support, and a clear view of how screens connect.

Install #

3.0 is a prerelease. flutter pub add zenrouter still resolves 2.x.

dependencies:
  zenrouter: ^3.0.0-beta.1

Which style #

Need deep linking, URL sync, or the browser back button?
│
├─ YES → Coordinator
│
└─ NO → Is the stack derived from state?
       │
       ├─ YES → Declarative
       │
       └─ NO  → Imperative

Imperative #

final path = NavigationPath<AppRoute>.create();

NavigationStack(
  path: path,
  resolver: (route) => StackTransition.material(route.build(context)),
);

path.push(ProfileRoute());
path.pop();

Example · Guide

Declarative #

NavigationStack.declarative diffs the list (Myers) and applies the minimum push/pop set. Override props on parameterized routes.

NavigationStack.declarative(
  routes: [
    for (final page in pages) PageRoute(page),
  ],
  resolver: (route) => StackTransition.material(...),
);

Example · Guide

Coordinator #

Coordinator is RouterConfig. Routes mix RouteUnique and implement toUri(). parseRouteFromUri turns a URI into a route.

abstract class AppRoute extends RouteTarget with RouteUnique {}

class HomeRoute extends AppRoute {
  @override
  Uri toUri() => Uri.parse('/');

  @override
  Widget build(covariant AppCoordinator coordinator, BuildContext context) {
    return Scaffold(
      body: ListTile(
        title: const Text('Product 42'),
        onTap: () => coordinator.push(ProductRoute(id: '42')),
      ),
    );
  }
}

class AppCoordinator extends Coordinator<AppRoute> {
  @override
  AppRoute parseRouteFromUri(Uri uri) {
    return switch (uri.pathSegments) {
      [] => HomeRoute(),
      ['products', final id] => ProductRoute(id: id),
      _ => NotFoundRoute(uri),
    };
  }
}

MaterialApp.router(routerConfig: AppCoordinator())

coordinator.push(ProductRoute(id: '42'));
coordinator.navigate(HomeRoute());
coordinator.replace(HomeRoute());
coordinator.pop();
await coordinator.pushUri(Uri.parse('/products/42'));

build is typed to your coordinator subclass.

Example · Coordinator guide

New Coordinator apps should declare a RouteManifest instead of growing that switch.

Layouts #

A RouteLayout owns a StackPath. Bind the constructor on the path and set layout on children.

late final shopStack = NavigationPath<AppRoute>.createWith(
  label: 'shop',
  coordinator: this,
)..bindLayout(ShopLayout.new);

class ShopHomeRoute extends AppRoute {
  @override
  Type? get layout => ShopLayout;
}

Layouts

Route mixins #

DevTools #

flutter pub add zenrouter_devtools

class AppCoordinator extends Coordinator<AppRoute>
    with CoordinatorDebug<AppRoute> {}

The overlay inspects stacks and can push a URI. Off in release (debugEnabled defaults to kDebugMode).

RouteManifest #

The recommended way to declare Coordinator routes in 3.0.

A parseRouteFromUri switch and each route's toUri() are two copies of the same paths. They drift. Overlaps (/products/new vs /products/:id) fail when a user hits the link, not when you ship. Layouts have no check that the shell in code matches the URL tree.

RouteManifest is the URI graph. RouteBinding is the only place that constructs a RouteTarget. Matching, reverse URLs, and the DevTools Graph tab all read that graph.

parseRouteFromUri still works. Use a manifest for new graphs.

class AppCoordinator extends Coordinator<AppRoute>
    with RouteModuleBinding<AppRoute, AppRouteId> {
  static final manifest = RouteManifest<AppRouteId>(
    name: 'app',
    idCodec: RouteIdCodec.enumValues(AppRouteId.values),
    routes: [
      RouteManifestRoute(id: AppRouteId.home, path: '/'),
      RouteManifestRoute(id: AppRouteId.product, path: '/products/:id'),
    ],
  );

  @override
  late final routeBindings = manifest.bind<AppRoute>(
    bindings: [
      RouteBinding(id: AppRouteId.home, create: (_) => HomeRoute()),
      RouteBinding(
        id: AppRouteId.product,
        create: (match) => ProductRoute(id: match.pathParameters['id']!),
      ),
    ],
    notFound: NotFoundRoute.new,
  );
}

The manifest has no widgets. RouteBinding is the factory from a match to a screen. RouteModuleBinding implements parseRouteFromUri. Bind every RouteManifestRoute; do not bind layout IDs.

Uri toUri() => AppCoordinator.manifest.location(
  AppRouteId.product,
  pathParameters: {'id': id},
);

:id is one segment. ...:slugs is a catch-all (match.restParameters['slugs']). Query strings are not part of the pattern.

With a manifest, also declare layouts as RouteManifestLayout and set parentId on children. A non-empty routeManifest enables the Graph tab in DevTools (topology + observed flow).

zenrouter_file_generator emits a coordinator, manifest, and bindings from lib/routes/.

Getting Started · Manifest example

Migrating from 2.x #

Apps that extend Coordinator still compile. parseRouteFromUri is unchanged.

Migration guide

Documentation #

• Getting Started
• Imperative · Declarative · Coordinator
• Layouts · Modular coordinator
• Recipes
• From go_router · From auto_route

Packages #

License #

Apache 2.0. LICENSE

definev