| name | flutter-auto-route-navigation |
| description | Implement typed routing, nested routes, and auth guards using auto_route in Flutter. Use when the task explicitly uses auto_route or its generated router; defer generic deep-link setup and other routing libraries. |
| metadata | {"triggers":{"files":["**/router.dart","**/app_router.dart"],"keywords":["AutoRoute","AutoRouter","router","guards","navigate","push"]}} |
AutoRoute Navigation
Priority: P1 (HIGH)
Structure
core/router/
├── app_router.dart # Router configuration
└── app_router.gr.dart # Generated routes
Implementation Workflow
- Annotate pages — Mark all screen/page widgets with
@RoutePage().
- Configure router — Extend
_$AppRouter and annotate with @AutoRouterConfig.
- Navigate with types — Use generated route classes (e.g.,
HomeRoute()). Never use strings.
- Add guards — Implement
AutoRouteGuard for authentication/authorization logic.
- Handle parameters — Constructors of
@RoutePage widgets automatically become route parameters.
- Prefer declarative calls — Use
context.pushRoute() or context.replaceRoute().
Nested Routes & Tabs
Use children in AutoRoute for tabs. Pass children parameter to define initial active sub-route.
See implementation examples for nested route navigation and router configuration patterns.
Reference & Examples
For full Router configuration and Auth Guard implementation:
See references/REFERENCE.md.
Anti-Patterns
- No string-based navigation: Use generated typed route classes (e.g.,
OrderDetailRoute(id: 123)).
- No protected screen without AutoRouteGuard: Every protected route must declare guard; don't rely on UI-level checks.
- No navigation calls from BLoC: Emit state and let Presentation layer navigate.
References
Canonical response anchors
When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
