manage-routes

Routing Management Skill

This skill defines the process for adding, modifying, and guarding routes using GoRouter with the _AppRoute base class, Routes registry, and the priority-ordered GateGuard/RouteGuard guards.

1. Directory Structure

lib/src/routes/
├── router.dart            # GoRouter config & auth shells
├── router.g.dart          # Auto-generated (Riverpod)
├── router_listenable.dart # Auth-state refresh listener
└── routes.dart            # _AppRoute base + Routes registry

2. Route Architecture

_AppRoute Base Class

Every route extends the private _AppRoute class which holds path, name, and a build method. It also provides toGoRoute() for zero-boilerplate registration:

abstract class _AppRoute {
  const _AppRoute({required this.path, required this.name});
  final String path;
  final String name;

  Widget build(BuildContext context, GoRouterState state);

  GoRoute toGoRoute() => GoRoute(
    name: name,
    path: path,
    builder: build,
  );
}

Routes Registry

All routes are registered as static const fields in the Routes class for autocomplete-friendly discovery:

abstract final class Routes {
  static const home = _HomeRoute();
  static const login = _LoginRoute();
  // ...
}

3. Step 1 — Define a New Route

Add a final class extending _AppRoute at the bottom of routes.dart:

final class _SearchRoute extends _AppRoute {
  const _SearchRoute()
      : super(path: '/search', name: 'search');

  @override
  Widget build(_, _) => const SearchPage();
}

For routes with path parameters, extract them from GoRouterState:

final class _DetailRoute extends _AppRoute {
  const _DetailRoute()
      : super(path: '/detail/:id', name: 'detail');

  @override
  Widget build(_, GoRouterState state) {
    final id = state.pathParameters['id']!;
    return DetailPage(id: id);
  }
}

If the route should be gated by a capability rather than just login state, pass requiredPermission: