home / skills / hoangnguyen0403 / agent-skills-standard / go-router-navigation

go-router-navigation skill

safe

This skill ensures type-safe navigation with go_router in Flutter apps, providing typed routes, redirection, and transitions for reliable routing.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill go-router-navigation

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

Files (1)

SKILL.md

1.6 KB

---
name: Flutter GoRouter Navigation
description: Typed routes, route state, and redirection using go_router.
metadata:
  labels: [navigation, go-router, routing]
  triggers:
    files: ['**/router.dart', '**/app_router.dart']
    keywords: [GoRouter, GoRoute, StatefulShellRoute, redirection, typed-routes]
---

# GoRouter Navigation

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

Type-safe deep linking and routing system using `go_router` and `go_router_builder`.

## Structure

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

## Implementation Guidelines

- **Typed Routes**: Always use `GoRouteData` from `go_router_builder`. Never use raw path strings.
- **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 the `redirect` property of the `GoRouter` config.
- **Parameters**: Use `@TypedGoRoute` to define paths with `:id` parameters.
- **Transitions**: Define standard transitions (Fade, Slide) in `buildPage`.
- **Navigation**: Use `MyRoute().go(context)` or `MyRoute().push(context)`.

## Code

```dart
// Route Definition
@TypedGoRoute<HomeRoute>(path: '/')
class HomeRoute extends GoRouteData {
  @override
  Widget build(context, state) => const HomePage();
}

// Router Config
final router = GoRouter(
  routes: $appRoutes,
  redirect: (context, state) {
    if (notAuthenticated) return '/login';
    return null;
  },
);
```

## Related Topics

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

Overview

This skill packages best practices for implementing type-safe navigation in Flutter using go_router and go_router_builder. It prioritizes typed routes, centralized router configuration, and clear redirection and parameter handling to reduce runtime routing errors. The guidance is practical and focused on maintainable route structures and predictable auth flows.

How this skill works

The skill enforces typed route definitions via GoRouteData and @TypedGoRoute annotations instead of raw path strings. It recommends a single global GoRouter registered in dependency injection, with nested TypedGoRoute children for related screens and a redirect callback for auth-based navigation. Standard transitions and navigation helpers (.go/.push) are suggested for consistent behavior.

When to use it

Building a medium-to-large Flutter app that requires reliable deep linking and refactor-safe routes.
Implementing authenticated sections where login state should trigger redirects.
Needing compile-time guarantees for route parameters (IDs, query params).
Standardizing navigation patterns across a team or multiple modules.

Best practices

Always define routes with @TypedGoRoute and GoRouteData; avoid raw path string usage.
Register one global GoRouter in your DI container to keep navigation centralized.
Nest related routes using TypedGoRoute children to mirror app structure and share shells.
Handle authentication and protected routes in the router's redirect callback, not in widgets.
Define transitions (Fade, Slide) in buildPage to maintain consistent UX across routes.

Example use cases

Protecting an app section: redirect unauthenticated users to /login from the router redirect.
Type-safe deep links: expose typed route constructors for external links and push/navigation calls.
Nested flows: model a settings section with child routes for profile, security, and preferences.
Parameterized pages: use @TypedGoRoute(path: '/items/:id') to pass and validate item IDs at compile time.

FAQ

Why use typed routes instead of string paths?

Typed routes provide compile-time checks for parameters and refactors, reducing runtime errors and making code easier to navigate.

Where should I handle login redirection?

Handle auth checks and redirection in the GoRouter redirect callback so routing decisions are centralized and widgets stay presentation-focused.