go_router_tree #

Code generator that builds route trees for go_router.

Features #

• Access to route names, relative paths, and full absolute paths.
• Generated helpers for goNamed, pushNamed, pushReplacementNamed, replaceNamed with required path parameters.
• Nested classes mirror the route hierarchy for IDE autocompletion.
• Compile-time validation: unique names and paths, safe path parameters, and clean path syntax.
• Pure Dart build step (no reflection), works with build_runner in Flutter and Dart projects.

Dependencies #

Add the packages to pubspec.yaml:

dependencies:
  # ...along with your other dependencies
  go_router: ^17.0.1
  go_router_tree_annotation: ^0.0.1

dev_dependencies:
  # ...along with your other dev-dependencies
  build_runner: ^2.10.4
  go_router_tree: ^0.0.1

Quick start #

1. Describe your route tree:

import 'package:go_router_tree_annotation/go_router_tree_annotation.dart';

@RouterTreeConfig(className: 'AppRoutes')
const routes = [
  RouteNode(
    name: 'root',
    path: '/',
  ),
  RouteNode(
    name: 'auth',
    path: '/auth',
    routes: [
      RouteNode(
        name: 'signIn',
        path: 'sign-in',
      ),
      RouteNode(
        name: 'signUp',
        path: 'sign-up',
      ),
    ],
  ),
  RouteNode(
    name: 'dashboard',
    path: '/dashboard',
    routes: [
      RouteNode(
        name: 'catalog',
        path: 'catalog',
        routes: [
          RouteNode(
            name: 'categoryDetails',
            path: ':categoryId',
            routes: [
              RouteNode(
                name: 'productDetails',
                path: 'product/:productId',
              ),
            ],
          ),
        ],
      ),
    ],
  ),
];

2. Generate code:

dart run build_runner build --delete-conflicting-outputs

The build will produce *.routes.g.dart with:

• static tree AppRoutes.routes;
• classes that mirror the node nesting;
• getters name, path, fullPath;
• navigation helpers: goNamed, pushNamed, pushReplacementNamed, replaceNamed.

3. Wire into GoRouter:

final routes = AppRoutes.routes;

final router = GoRouter(
  routes: [
    GoRoute(
      name: routes.root.name,
      path: routes.root.path,
      builder: (_, state) => const RootScreen(),
      routes: [
        GoRoute(
          name: routes.auth.name,
          path: routes.auth.path,
          builder: (_, state) => const AuthScreen(),
          routes: [
            GoRoute(
              name: routes.auth.signIn.name,
              path: routes.auth.signIn.path,
              builder: (_, state) => SignInScreen(state: state),
            ),
          ],
        ),
      ],
    ),
  ],
);

Typed navigation helpers:

routes.auth.signIn.goNamed(context);

routes.dashboard.catalog.categoryDetails.productDetails.goNamed(
  context,
  categoryId: 'books',
  productId: 'harry-potter',
  queryParameters: {'sort': 'desc'},
);

Validation #

• Route names are unique across the entire tree.
• Sibling paths are unique (normalized by path parameters).
• Nested paths cannot be "/" and must avoid trailing/double slashes.
• Forbidden characters: \ ? # & and whitespace.
• Path parameters are non-empty and cannot shadow parameters higher in the branch.

Tips #

• Top-level nodes should use absolute paths (/auth); nested nodes should use relative paths (sign-in).
• Generated files *.routes.g.dart are not meant to be edited by hand.
• See the full example and tests in example/ (uses example/lib/example.dart and example/test).