flutter-setup-declarative-routing

Implementing Routing and Deep Linking

Contents

• Core Concepts
• Workflow: Initializing the Application and Router
• Workflow: Configuring Platform Deep Linking
• Workflow: Implementing Nested Navigation
• Examples

Core Concepts

Use the go_router package for declarative routing in Flutter. It provides a robust API for complex routing scenarios, deep linking, and nested navigation.

• GoRouter: The central configuration object defining the application's route tree.
• GoRoute: A standard route mapping a URL path to a Flutter screen.
• ShellRoute / StatefulShellRoute: Wraps child routes in a persistent UI shell (e.g., a BottomNavigationBar). StatefulShellRoute maintains the state of parallel navigation branches.
• Path URL Strategy: Removes the default # fragment from web URLs, essential for clean deep linking across platforms.

Workflow: Initializing the Application and Router

Follow this workflow to bootstrap a new Flutter application with go_router and configure the root routing mechanism.

Task Progress

• Create the Flutter application.
• Add the go_router dependency.
• Configure the URL strategy for web/deep linking.
• Implement the GoRouter configuration.
• Bind the router to MaterialApp.router.

1. Scaffold the Application

Run the following commands to create the app and add the required routing package:

flutter create <app-name>
cd <app-name>
flutter pub add go_router

Run the create step only when starting a new app. In an existing project, go straight to adding the routing package. The URL strategy import in the example below needs the Flutter web plugins package, which ships with the Flutter SDK; declare it in the pubspec as an SDK dependency.

2. Configure the Router

Define a top-level GoRouter instance. Handle authentication or state-based routing using the redirect parameter. Deep links open routes directly, and the redirect also runs for StatefulShellRoute branches, so guard every route that can be reached from outside the app: check the sign in state and send signed out users to a login screen while keeping the requested location.

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';
import 'package:flutter_web_plugins/url_strategy.dart';

void main() {
  // Use path URL strategy to remove the '#' from web URLs
  usePathUrlStrategy();
  runApp(const MyApp());
}

final GoRouter _router = GoRouter(
  initialLocation: '/',
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'details/:id',
          builder: (context, state) => DetailsScreen(id: state.pathParameters['id']!),
        ),
      ],
    ),
  ],
  errorBuilder: (context, state) => ErrorScreen(error: state.error),
);

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routerConfig: _router,
      title: 'Routing App',
    );
  }
}

Treat path parameters from deep links as untrusted input. Check that the id has the expected form before using it in any lookup, and show the error screen when it does not. The error screen should show users only a generic page not found message and log error details only in debug builds.

Workflow: Configuring Platform Deep Linking

Configure the native platforms to intercept specific URLs and route them into the Flutter application.

Confirm the domain, package name, team ID and fingerprint with the user, and check that every placeholder value has been replaced in each edited or prepared file. Prepare the two association files for the user to review and deploy; the user publishes them to the domain.

Task Progress

• Determine target platforms (iOS, Android, or both).
• Apply conditional configuration for Android (Manifest + Asset Links).
• Apply conditional configuration for iOS (Plist + Entitlements + AASA).
• Run the listed adb and xcrun tests -> review errors -> fix.

If configuring for Android:

1. Modify AndroidManifest.xml: Add the intent filter inside the <activity> tag for .MainActivity.

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:host="yourdomain.com" />
    <data android:scheme="https" />
</intent-filter>

1. Host assetlinks.json: Serve the following JSON at https://yourdomain.com/.well-known/assetlinks.json.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourcompany.yourapp",
    "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"]
  }
}]

Ask the user to supply the public signing certificate fingerprint, for example from the Play Console app signing page. Use only that public value, and keep keystores and keystore passwords closed and out of logs.

If configuring for iOS:

1. Modify Info.plist: Opt-in to Flutter's default deep link handler. Note: Before adding this key, check the project dependencies for a third-party deep linking plugin (e.g., app_links). If one is present, set this to NO to prevent conflicts.

<key>FlutterDeepLinkingEnabled</key>
<true/>

1. Modify Runner.entitlements: Add the associated domain.

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:yourdomain.com</string>
</array>

1. Host apple-app-site-association: Serve the following JSON (without a .json extension) at https://yourdomain.com/.well-known/apple-app-site-association.

{
  "applinks": {
    "apps": [],
    "details": [{
      "appIDs": ["TEAM_ID.com.yourcompany.yourapp"],
      "paths": ["*"],
      "components": [{"/": "/*"}]
    }]
  }
}

Before hosting this file, replace the wildcard in both the paths and components keys with only the path prefixes the app actually routes, and exclude login, sign in callback and password reset pages. On Android, limit the intent filter to the same routes.

Validation Loop

Run the tests below -> review errors -> fix. Use only these listed tests, and ask the user to confirm that both association files are reachable on the domain.

• Android: Test using ADB.

  adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://yourdomain.com/details/123"' com.yourcompany.yourapp

• iOS: Test using xcrun on a booted simulator.

  xcrun simctl openurl booted https://yourdomain.com/details/123

Workflow: Implementing Nested Navigation

Use StatefulShellRoute to implement persistent UI shells (like a bottom navigation bar) that maintain the state of their child routes.

Task Progress

• Define StatefulShellRoute.indexedStack in the GoRouter configuration.
• Create StatefulShellBranch instances for each navigation tab.
• Implement the shell widget using StatefulNavigationShell.

final GoRouter _router = GoRouter(
  initialLocation: '/home',
  routes: [
    StatefulShellRoute.indexedStack(
      builder: (context, state, navigationShell) {
        return ScaffoldWithNavBar(navigationShell: navigationShell);
      },
      branches: [
        StatefulShellBranch(
          routes: [
            GoRoute(
              path: '/home',
              builder: (context, state) => const HomeScreen(),
            ),
          ],
        ),
        StatefulShellBranch(
          routes: [
            GoRoute(
              path: '/settings',
              builder: (context, state) => const SettingsScreen(),
            ),
          ],
        ),
      ],
    ),
  ],
);

Examples

High-Fidelity Shell Widget Implementation

Implement the UI shell that consumes the StatefulNavigationShell to handle branch switching.

class ScaffoldWithNavBar extends StatelessWidget {
  const ScaffoldWithNavBar({
    required this.navigationShell,
    super.key,
  });

  final StatefulNavigationShell navigationShell;

  void _goBranch(int index) {
    navigationShell.goBranch(
      index,
      // Support navigating to the initial location when tapping the active tab.
      initialLocation: index == navigationShell.currentIndex,
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: navigationShell,
      bottomNavigationBar: NavigationBar(
        selectedIndex: navigationShell.currentIndex,
        onDestinationSelected: _goBranch,
        destinations: const [
          NavigationDestination(icon: Icon(Icons.home), label: 'Home'),
          NavigationDestination(icon: Icon(Icons.settings), label: 'Settings'),
        ],
      ),
    );
  }
}

Programmatic Navigation

Use the context.go() and context.push() extension methods provided by go_router.

// Replaces the current route stack with the target route (Declarative)
context.go('/details/123');

// Pushes the target route onto the existing stack (Imperative)
context.push('/details/123');

// Pops the current route
context.pop();