go-router-navigation_skill

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.