home / skills / hoangnguyen0403 / agent-skills-standard / flutter-navigation

flutter-navigation skill

safe

This skill helps Flutter developers implement robust navigation using go_router, deep links, and named routes with proper validation and state preservation.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill flutter-navigation

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

Files (2)

SKILL.md

1.3 KB

---
name: Flutter Navigation
description: Flutter navigation patterns including go_router, deep linking, and named routes for Flutter apps.
metadata:
  labels: [flutter, navigation, routing, deep-linking, go-router]
  triggers:
    files: ['**/*_route.dart', '**/*_router.dart', '**/main.dart']
    keywords: [Navigator, GoRouter, routes, deep link, go_router, AutoRoute]
---

# Flutter Navigation

## **Priority: P1 (OPERATIONAL)**

Navigation and routing for Flutter apps using `go_router` or named routes.

## Guidelines

- **Package**: Use `go_router` for modern, declarative routing.
- **Deep Linking**: Configure `AndroidManifest.xml` and `Info.plist` for URL schemes.
- **Validation**: Validate parameters in `redirect` logic before navigation.
- **Stateful Tabs**: Use `IndexedStack` to preserve state in bottom navigation.

[Routing Patterns & Examples](references/routing-patterns.md)

## Anti-Patterns

- **No Manual URL Parsing**: Use `go_router` parsing, never `Uri.parse` manually.
- **No Stateless Tabs**: `Scaffold` body switching loses state; use `IndexedStack`.
- **No Unvalidated Deep Links**: Always check if IDs exist in `redirect`.
- **No Hardcoded Routes**: Use constants (e.g., `Routes.home`) or code generation.

## Related Topics

flutter-design-system | flutter-notifications | mobile-ux-core

Overview

This skill presents practical guidance for navigation and routing in Flutter apps, emphasizing go_router, deep linking, and named routes. It consolidates patterns, anti-patterns, and operational checks to make navigation predictable, testable, and maintainable. The recommendations target both single-screen flows and multi-tab apps.

How this skill works

The skill recommends using go_router as the primary routing mechanism for declarative, typed routes and built-in redirection. It explains how to configure platform deep links (AndroidManifest.xml and Info.plist), validate parameters in redirect logic, and preserve tab state with IndexedStack. It also highlights anti-patterns to avoid and suggests constants or code generation for route names.

When to use it

Building new Flutter apps that need a maintainable, declarative routing system.
Adding deep link support for Android and iOS to open specific screens from URLs.
Creating multi-tab layouts where preserving tab state is required.
Migrating from manual Uri parsing or ad-hoc route strings to a consistent routing approach.
Implementing parameter validation or guarded routes before navigation.

Best practices

Prefer go_router for modern, declarative routing and redirection hooks.
Configure deep links in AndroidManifest.xml and Info.plist and test on device.
Validate route parameters inside redirect or a route-level guard before navigation.
Preserve tab state with IndexedStack rather than swapping Scaffold bodies.
Keep route names as constants or use code generation to avoid hardcoded strings.
Avoid manual Uri.parse-based routing logic; rely on the router’s parsing.

Example use cases

Protecting a profile route by checking authentication in go_router redirect before pushing the page.
Handling incoming marketing deep links that open a product detail page with validated product IDs.
Implementing a bottom navigation with three tabs where each tab keeps its scroll position and internal state.
Migrating an app that used Navigator.pushNamed with scattered strings to a centralized go_router setup.
Using named route constants to generate typed route helpers for safer refactoring.

FAQ

Should I always use go_router instead of Navigator 2.0?

Use go_router unless you have highly custom navigator requirements; it builds on Navigator 2.0 and covers most routing, redirection, and deep-link needs with less boilerplate.

How do I prevent losing tab state when switching tabs?

Wrap tab pages in an IndexedStack so inactive tabs remain mounted; avoid replacing the Scaffold body directly as that unmounts and resets state.