name: "flutter-routing" description: "Declarative routing and navigation for Flutter using GoRouter and AutoRoute. Use when implementing navigation guards, nested routes, type-safe routing, or deep link handling." metadata: last_modified: "2026-03-12 11:18:17 (GMT+8)"
Flutter Routing & Navigation Architecture
Goal
Establish a robust, scalable, and declarative navigation system for Flutter applications. This skill ensures developers can correctly choose and implement industry-standard routing solutions—GoRouter for official declarative support or AutoRoute for type-safe code generation—while maintaining clean URL handling, deep-link support, and complex nested navigation architectures.
Process
🚀 High-Level Workflow
Navigating routing decisions requires understanding the project's scale and requirements for type safety versus boilerplate.
Phase 1: Choosing Your Framework
Determine the best fit for your team's workflow:
- GoRouter: The official, widely-supported declarative solution. Best for standard web-compatible routing and ease of external tool integration (like Sentry).
- AutoRoute: Compile-time type-safe routing. Best for massive apps where manual URL string management becomes a liability and strong type guarantees are prioritized.
Phase 2: Implementation Details
Consume these specialized architectural reference resources for deep implementation guidance:
- GoRouter & Persistent Navigation - Official declarative patterns,
StatefulShellRoutefor tabs, and redirection guards. - AutoRoute & Type-Safe Navigation - Code generation patterns (
v11.x),@RoutePageannotations, and global guards.
📚 Documentation Library
Refer to these detailed guides to implement specific routing features:
Constraints
- Declarative First: Prohibit legacy imperative
Navigator.pushpatterns in new architectures. All navigation should be addressable via URLs or generated Route objects. - Architecture Consistency: Never mix GoRouter and AutoRoute in the same application module.
- Web Compatibility: Ensure all routing logic maintains browser URL bar synchronization and back-button behavior integrity.
- Safe Parameters: Never pass massive Object instances directly through URL parameters; pass unique identifiers and fetch data at the target destination.