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:
@ScreenRouteon a widget, orScreenRoutesbeans in Dart configuration (like Spring WebFlux'sRouterFunctions), 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:
RouteFilterbeans send a navigation elsewhere; with the security starter,@PreAuthorizeon 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/catalogopens 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
# 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; an app lists only this package (spring_boot_starter_flutter_security brings it too). One import is enough:
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 and material_ui, and imports package:material_ui/material_ui.dart for the widgets:
# 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.
Example
An app with two tabs, a book screen with a path variable, a parameter and an extra object, and a not-found screen:
// 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}');
}
# 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
dart run build_runner build # registers the screens, writes BookPageRoute and the others
flutter run -d chrome
SpringApplicationWidgetwithouthomebuildsMaterialApp.router(orCupertinoApp.router,WidgetsApp.router, fromspring.flutter.app.type) on the router. Not set, the type is the one design starter's, elsewidgets; with both design starters it must be set.materialneeds the Material starter andcupertinothe 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:
@ScreenRoute, path patterns,context.route, generated constants, opening screens. - Transitions: the theme's transition, or one per screen or navigation.
- Shells and tabs:
@RouteShell, branches with their own stacks. - Routes in Dart configuration:
ScreenRoutesbeans. - Filters, guards and errors:
RouteFilter,@PreAuthorize, the not-found and error screens. - Beans per screen or branch: the
routeandbranchscopes. - Markdown screens:
content:andRouteContentView. - Languages: an address per language.
- The web and deep links: the address bar, pages for search engines, deep links.
- Testing: navigation in widget tests.
- All properties: every key of the starter.
- Differences from Spring
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.