
# spring_boot_starter_flutter_navigation

`spring_boot_starter_flutter_navigation` puts the screens of a Flutter app on routes. You mark a widget `@ScreenRoute('/catalog/books/{isbn}')`, and the starter opens it at that address, on the SDK's own `Router`: the browser's address bar, deep links and Android's back button all work, without `go_router`. Paths use Spring's patterns, the ones of `@GetMapping` in the web starter.

## Why

Navigation in Flutter is either imperative (`Navigator.push`, no addresses, no deep links) or a routing package whose tables are kept by hand next to the screens. Here a screen declares its own address, the generator checks every route and writes typed constants for it, and the rest is configuration:

- **Screens on routes**: `@ScreenRoute` on a widget, or `ScreenRoutes` beans in Dart configuration (like Spring WebFlux's `RouterFunctions`), merged and checked at the start: a path declared twice names both places.
- **Typed navigation**: `BookPageRoute.to(isbn: ..., page: 2)` and a typed key per value, so a renamed path or parameter breaks the build, not the app.
- **Shells**: `@RouteShell(branches: [...])` keeps the tabs while the screens of a branch change; each branch keeps its own stack.
- **Filters and guards**: `RouteFilter` beans send a navigation elsewhere; with the security starter, `@PreAuthorize` on a screen sends nobody logged in to the login and back.
- **Scopes**: beans that live as long as a screen or a branch.
- **Markdown screens**: one address per Markdown file of a folder, shown with the theme.
- **Languages in the address**: `/ja/catalog` opens the catalog in Japanese.
- **The web and deep links**: addresses without `#`, a page per route for search engines, the deep link files of iOS, macOS and Android, all from properties.

## Setup

```yaml
# pubspec.yaml
dependencies:
  spring_boot_starter_flutter_navigation: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
```

The starter brings and re-exports [spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md); an app lists only this package (`spring_boot_starter_flutter_security` brings it too). One import is enough:

```dart
import 'package:spring_boot_starter_flutter_navigation/spring_boot_starter_flutter_navigation.dart';
```

The router imports neither Material nor Cupertino, so an app of `spring.flutter.app.type: widgets` (the type without a design starter) has no design library in its build. An app that shows Material widgets, as the example below does, also lists [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md) and `material_ui`, and imports `package:material_ui/material_ui.dart` for the widgets:

```yaml
# pubspec.yaml
dependencies:
  material_ui: ^1.11.0
  spring_boot_starter_flutter_material: ^0.9.0
  spring_boot_starter_flutter_navigation: ^0.9.0
```

A Cupertino app lists `spring_boot_starter_flutter_cupertino` and `cupertino_ui` instead. The starter needs Flutter 3.50 or later (Dart 3.14). See [Design libraries](../spring-boot-starter-flutter/design-libraries.md).

## Example

An app with two tabs, a book screen with a path variable, a parameter and an extra object, and a not-found screen:

```dart
// lib/main.dart
import 'package:material_ui/material_ui.dart';
import 'package:spring_boot_starter_flutter_navigation/spring_boot_starter_flutter_navigation.dart';

import 'spring_gen/main.spring.dart';

// No home: the app widget is built on the router.
@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(application: () => springApplication),
);

class BookSummary {
  const BookSummary(this.title);
  final String title;
}

// The tabs; each branch keeps its own stack of screens.
@RouteShell(branches: ['/catalog', '/profile'])
class MainTabs extends StatelessWidget {
  const MainTabs(this.shell, {super.key});
  final ShellState shell;

  @override
  Widget build(BuildContext context) => Scaffold(
    body: shell.child,
    bottomNavigationBar: NavigationBar(
      selectedIndex: shell.index,
      onDestinationSelected: shell.select,
      destinations: const [
        NavigationDestination(icon: Icon(Icons.book), label: 'Catalog'),
        NavigationDestination(icon: Icon(Icons.person), label: 'Profile'),
      ],
    ),
  );
}

@ScreenRoute('/catalog', title: 'Catalog')
class CatalogPage extends StatelessWidget {
  const CatalogPage({super.key});

  @override
  Widget build(BuildContext context) => ListView(
    children: [
      ListTile(
        title: const Text('Dune'),
        // A generated, typed address: a renamed parameter does not compile.
        onTap: () => context.route.go(
          BookPageRoute.to(isbn: '978-0441013593', page: 1, extra: const BookSummary('Dune')),
        ),
      ),
    ],
  );
}

@ScreenRoute('/catalog/books/{isbn}', title: 'Book', params: {'page': int}, extra: BookSummary)
class BookPage extends StatelessWidget {
  const BookPage({super.key});

  @override
  Widget build(BuildContext context) {
    final route = context.route;
    final isbn = route.get(BookPageRoute.isbn);        // String
    final page = route.get(BookPageRoute.page) ?? 1;   // int?
    final summary = route.get(BookPageRoute.extra);    // BookSummary?
    return Text('${summary?.title ?? isbn}, page $page');
  }
}

@ScreenRoute('/profile', title: 'Profile')
class ProfilePage extends StatelessWidget {
  const ProfilePage({super.key});

  @override
  Widget build(BuildContext context) => const Text('Profile');
}

@ScreenRoute.notFound()
class NotFoundPage extends StatelessWidget {
  const NotFoundPage({super.key});

  @override
  Widget build(BuildContext context) => Text('Nothing at ${context.route.uri}');
}
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    # A MaterialApp: spring_boot_starter_flutter_material, the one design
    # starter, decides the app's type (spring.flutter.app.type not needed)
    navigation:
      initial: /catalog
```

## Running it

```bash
dart run build_runner build   # registers the screens, writes BookPageRoute and the others
flutter run -d chrome
```

- `SpringApplicationWidget` without `home` builds `MaterialApp.router` (or `CupertinoApp.router`, `WidgetsApp.router`, from `spring.flutter.app.type`) on the router. Not set, the type is the one design starter's, else `widgets`; with both design starters it must be set. `material` needs the Material starter and `cupertino` the Cupertino starter: without it the start fails and names the starter to add.
- The routes are checked at the start: a path declared twice, a branch no shell has, a guarded screen without a security starter stop it with a report.
- In a browser the address bar shows `/catalog/books/978-0441013593?page=1`; a reload opens the same screen (the extra object is lost, so it is always optional).

## What is inside

- [Screens and routes](screens.md): `@ScreenRoute`, path patterns, `context.route`, generated constants, opening screens.
- [Transitions](transitions.md): the theme's transition, or one per screen or navigation.
- [Shells and tabs](shells.md): `@RouteShell`, branches with their own stacks.
- [Routes in Dart configuration](dart-configuration.md): `ScreenRoutes` beans.
- [Filters, guards and errors](filters-and-guards.md): `RouteFilter`, `@PreAuthorize`, the not-found and error screens.
- [Beans per screen or branch](scopes.md): the `route` and `branch` scopes.
- [Markdown screens](markdown-screens.md): `content:` and `RouteContentView`.
- [Languages](languages.md): an address per language.
- [The web and deep links](web-and-deep-links.md): the address bar, pages for search engines, deep links.
- [Testing](testing.md): navigation in widget tests.
- [All properties](properties.md): every key of the starter.
- [Differences from Spring](differences.md)

## In Spring (Java)

Spring has no navigation for apps. The names follow Spring where there is something to follow: path patterns (`@GetMapping`'s), `RouterFunctions` (Spring WebFlux), `*Template` for the API, scopes for beans, `@PreAuthorize` for guards.

## See also

- [spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md)
- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
- [The generator for Flutter](../spring-core-dart-generator/flutter/index.md)
- [What a build contains](optimizations.md)
