Manage App Navigation

Routing is implemented with go_router and a thin RouterService wrapper so navigation can still be triggered from ViewModels without passing BuildContext around.

This gives you URL synchronization and deep linking on web, while keeping navigation logic simple and testable.

Default Routes

The boilerplate comes with two routes which should always exist:

• / - The home page.
• /404 - The 404 page, when a route is not found.

1
final routes = [
2
  GoRoute(
3
    path: RoutePaths.home,
4
    pageBuilder: (context, state) => _buildPage(const HomeView(), state),
5
  ),
6
  GoRoute(
7
    path: RoutePaths.notFound,
8
    pageBuilder: (context, state) => _buildPage(const NotFoundView(), state),
9
  ),
10
];

Adding a New Route

Add new routes using GoRoute.

1
GoRoute(
2
  path: '/new-route',
3
  pageBuilder: (context, state) => _buildPage(const NewRouteView(), state),
4
),

Dynamic route params use : in the path.

1
GoRoute(
2
  path: '/new-route/:id',
3
  pageBuilder: (context, state) {
4
    final id = state.pathParameters['id'];
5
    return _buildPage(NewRouteView(id: id), state);
6
  },
7
),

Use nested routes for parent-child relationships. Child routes should use relative paths (no leading /).

Using a Route

RouterService exposes go_router-aligned methods only.

go

Default navigation method. Updates the URL and rebuilds stack from route hierarchy.

1
locator<RouterService>().go('/new-route');

push

Pushes a temporary page/flow on top of the stack.

1
locator<RouterService>().push('/new-route');

replace

To replace the current route, you can use the replace method.

1
locator<RouterService>().replace('/new-route');

canPop and pop

Back navigation checks are available through canPop().

1
if (locator<RouterService>().canPop()) {
2
  locator<RouterService>().pop();
3
}

Passing Data to a Route

There are 3 common ways to pass data.

Path Parameters

As shown above, dynamic segments become pathParameters.

1
// configure the route in route_config.dart
2
GoRoute(
3
  path: '/todos/:id',
4
  pageBuilder: (context, state) {
5
    final id = state.pathParameters['id'];
6
    return _buildPage(TodoView(id: id), state);
7
  },
8
),
9

10
// go to the route
11
locator<RouterService>().go('/todos/123');

Query Parameters

You can also pass data in the URL query string.

1
// configure the route in route_config.dart
2
GoRoute(
3
  path: '/todos',
4
  pageBuilder: (context, state) {
5
    final id = state.uri.queryParameters['id'];
6
    return _buildPage(TodoView(id: id), state);
7
  },
8
),
9

10
// go to the route
11
locator<RouterService>().go('/todos?id=123');

Extra

For non-URL data, pass a typed object using extra.

1
// configure the route in route_config.dart
2
GoRoute(
3
  path: '/todos',
4
  pageBuilder: (context, state) {
5
    final todo = state.extra as Todo;
6
    return _buildPage(TodoView(id: todo.id, name: todo.name), state);
7
  },
8
),
9

10
// go to the route
11
locator<RouterService>().go('/todos', extra: Todo(id: '123', name: 'Test'));

Automatic Routing Depending on Auth

For auth-based navigation, keep guard logic in router configuration instead of scattering checks across ViewModels.

Pass auth-aware routing hooks into RouterService:

• redirect for auth guard decisions (for example login-gated routes)
• refreshListenable so auth state changes trigger redirect re-evaluation

This keeps auth routing centralized while still using RouterService methods (go, push, replace, pop) for normal app navigation.

Unknown routes are redirected to /404 through the router exception handler with a loop guard, so you get a stable not-found flow without manual stack management.