Flutter Go Router NavigationSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: flutter-go-router-navigation
description: Implement typed routes, redirection, and guards using go_router in Flutter. Use when changing go_router navigation; defer widget tests that merely assert redirect behavior and defer slide/transition animation work.
metadata:
  triggers:
    files:
      - "**/router.dart"
      - "**/app_router.dart"
    keywords:
      - GoRouter
      - GoRoute
      - StatefulShellRoute
      - redirection
      - typed-routes
---

# GoRouter Navigation

## **Priority: P0 (CRITICAL)**

## Structure

```text
core/router/
├── app_router.dart # Router configuration
└── routes.dart # Typed route definitions (GoRouteData)
```

## Implementation Guidelines

- **Typed Routes**: Always use **GoRouteData** and **@TypedGoRoute** from `go_router_builder`. Never use raw path strings.
- **Parameters**: Define strongly-typed parameters in route class (e.g., `class OrderDetailRoute extends GoRouteData { final String id; }`) with paths like **'/orders/:id'**.
- **Root Router**: One global `GoRouter` instance registered in DI.
- **Sub-Routes**: Nest related routes using `TypedGoRoute` and children lists.
- **Redirection**: Handle Auth (Login check) in **redirect callback** of `GoRouter` config: `redirect: (context, state) => isLoggedIn ? null : '/login'`. ** NOT check auth inside page widget.**
- **Tabs**: Use **StatefulShellRoute** with branches for bottom tab bar (Home, Orders, Profile) so each tab maintains its own navigation stack.
- **Transitions**: Define standard transitions (Fade, Slide) in `buildPage`.
- **Navigation**: Use **MyRoute().go(context)** or `MyRoute().push(context)`. Using **OrderDetailRoute(id: id).go(context)** only allowed way to navigate.

## Code

See [references/typed-routes.md](references/typed-routes.md) for GoRouteData + redirect implementation.

## Anti-Patterns

- **No Raw String Paths**: Use typed `GoRouteData` classes (e.g., `OrderDetailRoute(id: 123).go(context)`) instead of `context.go('/orders/123')`
- **No Inline Auth Logic**: Redirect logic belongs in `GoRouter.redirect`, not UI's `build()` method
- **No Multiple Routers**: Register one global `GoRouter` instance in DI
- **No Unvalidated IDs**: Always verify parameters exist in `redirect` before building route

## Related Topics

layer-based-clean-architecture | auto-route-navigation | security

## Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

- redirect callback

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.