navigation-and-routing

Construct exactly one GoRouter in a routing directory, expose it through a Riverpod provider, and hand it to a single MaterialApp.router in app.dart. Define routes as a declarative tree of GoRoutes with typed path constants rather than hand-concatenated strings.

context.go replaces the navigation stack and suits tab roots or post-login destinations, while context.push stacks a page you expect to pop back from, such as a detail or edit screen. Mixing them incorrectly breaks the system back button.

Write a pure redirect function that takes an auth state snapshot and GoRouterState and returns a location string or null. Bridge your auth provider to a refreshListenable so the router re-evaluates guards when auth changes, and always allow the guard's own target to avoid redirect loops.

state.extra holds a live in-memory Dart object that is not serialized, so it is null on cold-start deep links and after process death or state restoration. Put screen identity in path parameters so the URL alone fully reconstructs the screen, and treat extra only as an optional preloaded-object optimization.

Use StatefulShellRoute.indexedStack, which keeps each branch's navigation stack alive in an IndexedStack across tab switches. Switch branches with navigationShell.goBranch, passing initialLocation when re-tapping the active tab to return it to its root.

Use PopScope with canPop set to false while the form is dirty, then handle onPopInvokedWithResult to show a confirmation dialog and only pop after the user confirms. WillPopScope is removed, and you must guard any post-await context use with context.mounted.