Routing (GoRouter)

When to use

• Adding a new screen or feature entry point.
• Implementing deep linking or redirection (e.g., AuthGuard).
• Passing arguments between screens.

Setup

Define a centralized local_router.dart (or similar) in core/router/ or app/router/. Prefer nested/sub-routes over a flat list so deep links and back navigation remain predictable.

final goRouter = GoRouter(
  initialLocation: '/',
  debugLogDiagnostics: true,
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomePage(),
      routes: [
        GoRoute(
          path: 'details/:id',
          builder: (context, state) {
            final id = state.pathParameters['id']!;
            return DetailPage(id: id);
          },
        ),
      ],
    ),
  ],
);

Best Practices

1) Type-Safe Arguments

Preferred: go_router_builder with @TypedGoRoute

When go_router_builder is available, annotate route data classes:

@TypedGoRoute<OrdersRoute>(name: 'orders', path: '/orders')
@immutable
class OrdersRoute extends GoRouteData {
  const OrdersRoute();

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return const OrdersScreen();
  }
}

// With parameters:
@TypedGoRoute<OrderDetailRoute>(name: 'order-detail', path: '/orders/:id')
@immutable
class OrderDetailRoute extends GoRouteData {
  const OrderDetailRoute({required this.id});
  final String id;

  @override
  Widget build(BuildContext context, GoRouterState state) {
    return OrderDetailScreen(id: id);
  }
}

// Navigate:
const OrdersRoute().go(context);
OrderDetailRoute(id: orderId).go(context);

Fallback (no go_router_builder): Use goNamed with string constants defined in a central route-names file. Never inline path strings in widget code.

• Use path parameters for IDs (e.g. details/:id).
• Use query parameters for filtering/sorting state (for example: ?status=paid&page=2).
• Use extra for complex objects only if necessary. Prefer passing an ID and refetching data to ensure the screen is independent and deep-linkable.
• Prefer typed routes or goNamed over raw path strings where possible.
• Keep route path segments lowercase kebab-case (for example user/update-address).

2) Redirects (Guards)

• implement redirect logic at the top level or per-route.

redirect: (context, state) {
  final isLoggedIn = authBloc.state.isAuthenticated;
  final isLoggingIn = state.uri.path == '/login';

  if (!isLoggedIn && !isLoggingIn) return '/login';
  if (isLoggedIn && isLoggingIn) return '/';

  return null;
},

3) Navigation

• Use context.go('/details/123') or context.goNamed(...) for normal app/deep-linkable navigation.
• Use context.push('/details/123') when the route is transient and should return a result on pop.
• Prefer BuildContext extensions (context.goNamed, context.pushNamed) over GoRouter.of(context) for consistency.