home / skills / hoangnguyen0403 / agent-skills-standard / auto-route-navigation

auto-route-navigation skill

safe

This skill helps you implement safe Flutter navigation with AutoRoute by generating typed routes, nested navigation, guards, and declarative context navigation.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill auto-route-navigation

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.5 KB

---
name: Flutter AutoRoute Navigation
description: Typed routing, nested routes, and guards using auto_route.
metadata:
  labels: [navigation, auto-route, routing]
  triggers:
    files: ['**/router.dart', '**/app_router.dart']
    keywords: [AutoRoute, AutoRouter, router, guards, navigate, push]
---

# AutoRoute Navigation

## **Priority: P1 (HIGH)**

Type-safe routing system with code generation using `auto_route`.

## Structure

```text
core/router/
├── app_router.dart # Router configuration
└── app_router.gr.dart # Generated routes
```

## Implementation Guidelines

- **@RoutePage**: Annotate all screen/page widgets with `@RoutePage()`.
- **Router Config**: Extend `_$AppRouter` and annotate with `@AutoRouterConfig`.
- **Typed Navigation**: Use generated route classes (e.g., `HomeRoute()`). Never use strings.
- **Nested Routes & Tabs**: Use `children` in `AutoRoute` for tabs. When navigating to a route with nested tabs, use the `children` parameter to define the initial active sub-route (e.g., `context.navigateTo(OrdersTabRoute(children: [ViewByOrdersPageRoute()]))`).
- **Guards**: Implement `AutoRouteGuard` for authentication/authorization logic.

- **Parameters**: Constructors of `@RoutePage` widgets automatically become route parameters.
- **Declarative**: Prefer `context.pushRoute()` or `context.replaceRoute()`.

## Reference & Examples

For full Router configuration and Auth Guard implementation:
See [references/REFERENCE.md](references/REFERENCE.md).

## Related Topics

go-router-navigation | layer-based-clean-architecture

Overview

This skill teaches typed, declarative navigation in Flutter using auto_route. It focuses on generated route classes, nested routes (tabs), and guard-based authorization to keep navigation type-safe and maintainable. The guidance enforces code-generation patterns and practical navigation APIs for predictable routing behavior.

How this skill works

The skill inspects router configuration and page annotations to ensure screens are annotated with @RoutePage and the router extends _$AppRouter with @AutoRouterConfig. It enforces use of generated route classes instead of string paths, validates nested children usage for tabbed routes, and recommends implementing AutoRouteGuard for auth flows. It also promotes using context.pushRoute(), context.replaceRoute(), and context.navigateTo() with children to set initial nested routes.

When to use it

Building a Flutter app that requires type-safe navigation and compile-time route checks
Implementing nested tab flows where each tab has its own sub-route stack
Protecting routes with authentication or role-based guards
Migrating from string-based routing to a generated, maintainable router
Ensuring route parameters map directly to widget constructors

Best practices

Annotate all screen widgets with @RoutePage() so constructors become route parameters
Extend _$AppRouter and annotate with @AutoRouterConfig for centralized router setup
Always use generated route classes (e.g., HomeRoute()) — never hard-coded strings
Use children in AutoRoute to define nested routes and pass children when navigating to set the initial active tab
Implement AutoRouteGuard for authentication and authorization checks
Prefer declarative navigation APIs: context.pushRoute(), context.replaceRoute(), or context.navigateTo() with children

Example use cases

Main app router located under core/router with app_router.dart and generated app_router.gr.dart for compile-time safety
Navigating to a tabbed route while selecting an initial tab: context.navigateTo(OrdersTabRoute(children: [ViewByOrdersPageRoute()]))
Protecting a checkout route with an AutoRouteGuard that redirects unauthenticated users to a login route
Passing typed parameters to a details screen via its constructor-generated route parameter (e.g., ProductDetailsRoute(productId: 42))
Replacing the stack after login using context.replaceRoute(HomeRoute()) to prevent back navigation

FAQ

Do I still need string paths with auto_route?

No. Use the generated route classes for type safety and to avoid brittle string paths.

How do I set the initial tab when navigating to a nested route?

Pass the desired child route in the children parameter, for example: context.navigateTo(OrdersTabRoute(children: [ViewByOrdersPageRoute()])).