navigation-and-routing

Navigation and routing

This skill owns app navigation with go_router. There is exactly ONE GoRouter for the app, defined in lib/routing/, and every screen is reachable by a URL. Navigation is a data structure (routes + a pure redirect), not a pile of imperative Navigator.push calls.

Read the reference for the task at hand:

• references/go-router-config.md — the single router, context.go vs context.push, path params vs state.extra, typed route helpers, errorBuilder/404.
• references/guards-and-redirects.md — pure redirect functions, the Riverpod refreshListenable, auth + onboarding gates, avoiding redirect loops.
• references/shells-and-deep-links.md — StatefulShellRoute.indexedStack for bottom-nav/rail shells, CustomTransitionPage, PopScope, and notification-payload → location mapping.

Run scripts/check_routing.sh before a PR.

Non-negotiable rules

1. Exactly ONE `GoRouter`, built in `lib/routing/`, wired once via `MaterialApp.router` in `app.dart`. Multiple routers fragment history, deep links, and back-button behaviour. The router is created behind a provider so guards can watch app state.
2. Deep-linkable identity lives in PATH PARAMS, never in `state.extra`. extra is a live Dart object: it is null on a cold start from a deep link and after process death / restoration. A screen that needs an id to rebuild must read it from state.pathParameters so the URL alone fully reconstructs the screen.
3. `state.extra` is ONLY an optional non-identity optimisation (a pre-fetched object to avoid a reload flash). The screen must still work — refetch by id — when extra is null.
4. Use `context.go` to replace the stack (declarative destinations, tabs, post-login home); use `context.push` to stack a screen you expect to pop back from (a detail, a modal flow). Mixing them wrong breaks the back button. Know which one every call site needs.
5. Guards are PURE `redirect` functions. redirect returns a new location String? (or null to allow) from GoRouterState + a snapshot of app state. No I/O, no navigation calls, no side effects inside redirect — it runs on every navigation and can run repeatedly.
6. Reactive guards use a `refreshListenable`, not polling. Bridge the Riverpod auth/onboarding provider to a Listenable; the router re-evaluates redirect whenever it fires. See state-management-riverpod.
7. Redirects must be loop-free. Always allow the destination the guard sends you TO (e.g. never redirect /sign-in back to /sign-in). Guard against A→B→A by checking the current location before redirecting.
8. Tab/branch shells use `StatefulShellRoute.indexedStack`. It preserves each branch's navigation stack and state across tab switches; a plain ShellRoute with an IndexedStack you wire by hand does not survive router rebuilds as cleanly. Switch branches with navigationShell.goBranch(index).
9. Custom transitions go through `CustomTransitionPage` and respect reduced motion. When the platform requests reduced motion, collapse to a no-op/fade. Read the flag from MediaQuery, resolve motion via the design system — see accessibility-as-code and design-system-structure.
10. Intercept back / unsaved changes with `PopScope`, not `WillPopScope` (removed). Set canPop: false and handle in onPopInvokedWithResult(bool didPop, T? result); only navigate away after the user confirms.
11. Provide an `errorBuilder` and a real 404/error route. An unmatched deep link must land on a designed error screen, never a red error box.
12. Never hold a `BuildContext` across an `await` before navigating. Capture GoRouter.of(context) (or the router) before the await, or guard with context.mounted after. See async-safety.
13. A feature does not build its own router. scaffold-feature-module registers a feature's GoRoute INTO this router's route list; features never instantiate GoRouter.

The single router

app.dart reads the router from a provider and hands it to MaterialApp.router. The router itself lives in routing/ and is the only place GoRouter(...) is constructed.

// routing/app_router.dart
final routerProvider = Provider<GoRouter>((ref) {
  // Bridge Riverpod auth state to a Listenable the router can watch.
  final refresh = ValueNotifier<int>(0);
  ref.onDispose(refresh.dispose);
  ref.listen(authNotifierProvider, (_, __) => refresh.value++);

  return GoRouter(
    initialLocation: Routes.home,
    refreshListenable: refresh,
    redirect: (context, state) => appRedirect(ref.read(authNotifierProvider), state),
    errorBuilder: (context, state) => ErrorScreen(error: state.error),
    routes: $appRoutes, // assembled from feature route lists
  );
});

// app.dart — the only MaterialApp.router
class MyApp extends ConsumerWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final router = ref.watch(routerProvider);
    return MaterialApp.router(
      routerConfig: router,
      theme: lightTheme,
      darkTheme: darkTheme,
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
    );
  }
}

Identity in the path, not in extra

// GOOD: id is in the URL — a cold-start deep link to /items/42 fully rebuilds.
GoRoute(
  path: '/items/:id',
  builder: (context, state) {
    final id = state.pathParameters['id']!; // always present
    // extra is an OPTIONAL fast-path; screen must work when it is null.
    final preloaded = state.extra as Item?;
    return ItemScreen(itemId: id, preloaded: preloaded);
  },
),

// BAD: identity smuggled through extra — null on cold start / after process death.
context.push('/item', extra: item); // no id in the URL => not deep-linkable

Typed route helpers (constants, not string soup)

Prefer small constant/builder classes so call sites never hand-concatenate paths. go_router_builder codegen is an OPTIONAL upgrade, not the default.

// routing/routes.dart
abstract final class Routes {
  static const home = '/';
  static const items = '/items';
  static String item(String id) => '/items/$id';
  static const signIn = '/sign-in';
}

// call site
context.push(Routes.item(item.id));

go vs push

context.go(Routes.home);          // replace whole stack: post-login, tab roots
context.push(Routes.item(id));    // stack a detail you'll pop back from
context.pop(result);              // return up, optionally with a result

Anti-patterns

• Two GoRouter instances, or a nested Navigator/MaterialApp inside a screen for "sub-navigation." Use nested routes / StatefulShellRoute.
• Passing a domain id through state.extra and reading extra! in build — crashes on cold start.
• I/O, ref.read of async work, or calling context.go INSIDE redirect. Redirect is pure and returns a location.
• A redirect that can bounce forever because it also redirects its own target.
• Mixing Navigator.pushNamed('/x') string routes with go_router — one navigation system only.
• WillPopScope (removed) instead of PopScope.
• Awaiting then using the same context to navigate without a mounted check.
• A feature package/folder constructing its own GoRouter.

Definition of done

• One GoRouter in lib/routing/, one MaterialApp.router in app.dart.
• Every screen reachable by a URL; every id-bearing screen reads its id from state.pathParameters.
• state.extra is only ever an optional optimisation; every such screen renders correctly with extra == null.
• Guards are pure redirect functions with a refreshListenable; no redirect loops.
• Tab shells use StatefulShellRoute.indexedStack; branch state survives tab switches.
• Transitions respect reduced motion; errorBuilder + 404 route present.
• PopScope guards unsaved changes; no BuildContext used across an await when navigating.
• scripts/check_routing.sh passes.

Related skills

• app-startup-and-bootstrap — owns main()/bootstrap() ordering and where MaterialApp.router is mounted.
• state-management-riverpod — the auth/onboarding providers the refreshListenable bridges.
• scaffold-feature-module — registers a feature GoRoute into this router.
• adaptive-layout — chooses NavigationRail vs BottomNavigationBar by width for the shell.
• accessibility-as-code — reduced-motion flag and semantics for navigation.
• design-system-structure — the reduced-motion token / resolveMotion helper for transitions.
• async-safety — BuildContext/mounted rules around awaited navigation.
• local-notifications-scheduler — the notification payload whose pure mapper produces a location.

References

• gorouter package: https://pub.dev/packages/gorouter
• gorouter API docs: https://pub.dev/documentation/gorouter/latest/
• Flutter navigation & routing: https://docs.flutter.dev/ui/navigation
• Deep linking: https://docs.flutter.dev/ui/navigation/deep-linking
• PopScope API: https://api.flutter.dev/flutter/widgets/PopScope-class.html