spring_boot_starter_flutter
spring_boot_starter_flutter brings Spring Boot into a Flutter app. You write your services and your app state as plain classes marked @Component(). The framework creates one object of each, a bean, and connects them: a bean that needs another one asks for it in its constructor. All beans live in the application context, which starts when the app starts. The starter puts that context into the widget tree, so any widget can get the beans it needs, and widgets that show a bean's state rebuild when it changes.
You do not need to know Spring to use it. If you do, you will find the same model: @Component, @Value, @ConfigurationProperties, profiles, events and application.yml.
Why
A Flutter app has no standard place for its services and its shared state. Each app picks a state library, passes objects through constructors, and keeps its settings in Dart code. The starter gives one model for all of it:
- State and services are beans. A widget lists the beans it needs in its type and gets them in
build. NoProvidertree, no constructor chains. - State beans notify by themselves. A class marked
@ChangeNotifierComponent()needs nonotifyListeners()call: its generated proxy makes it after every method. - The app is configuration. The app widget (
WidgetsApp, orMaterialAppandCupertinoAppwith their design starters), its title, languages, themes, splash screen and keyboard shortcuts are written inapplication.yml, not in code. - The platform is a profile.
application-ios.ymlis read on iPhones only,application-release.ymlin release builds only, and a bean marked@Profile(['android'])exists on Android only. - The app follows its lifecycle. In the background,
@Scheduledtasks and WebSocket connections stop; they start again when the app comes back. - A hot reload that changed beans restarts the context with the new code.
Setup
# pubspec.yaml
dependencies:
flutter:
sdk: flutter
spring_boot_starter_flutter: ^0.9.0
dev_dependencies:
build_runner: ^2.17.0
spring_core_dart_generator: ^0.9.0 # required: it writes the application
flutter_test:
sdk: flutter
spring_boot_starter_test: ^0.9.0 # springBootTest and BeanOverride, for tests
Then:
- Put
@SpringBootApplication()onmaininlib/main.dart. - Run
dart run build_runner watch(orbuild). The generator writeslib/spring_gen/main.spring.dart, withspringApplication: the application, with every bean found underlib/. Keepwatchrunning while you work. - Put configuration files and message files into
lib/resources/. The generator embeds them into the generated code, so they need noflutter: assets:entry.
The Flutter packages need Flutter 3.50 or later (Dart 3.14).
The starter has no design library: it imports package:flutter/widgets.dart only, and an app of the default type widgets has neither Material nor Cupertino in its build. An app with Material or Cupertino widgets adds spring_boot_starter_flutter_material or spring_boot_starter_flutter_cupertino, and material_ui or cupertino_ui. See Design libraries.
One import is enough. package:spring_boot_starter_flutter/spring_boot_starter_flutter.dart also exports spring_core_dart, spring_boot_dart, spring_web_dart (the HTTP clients) and spring_boot_starter_logging. Two names are left out because Flutter has its own: Boot's startup Banner (Flutter has a Banner widget) and the validation constraint Size (dart:ui has Size), which is exported as SizeConstraint.
Example
A complete counter app. It uses Material's Scaffold, FloatingActionButton and Icons, so it adds the Material starter and material_ui:
# pubspec.yaml
dependencies:
flutter:
sdk: flutter
material_ui: ^1.11.0
spring_boot_starter_flutter_material: ^0.9.0 # brings spring_boot_starter_flutter
// lib/main.dart
import 'package:material_ui/material_ui.dart';
import 'package:spring_boot_starter_flutter_material/spring_boot_starter_flutter_material.dart';
import 'spring_gen/main.spring.dart'; // written by the generator
@SpringBootApplication()
void main() => runApp(
SpringApplicationWidget(
application: () => springApplication,
// The app widget around it is built from spring.flutter.app.*.
home: const CounterPage(),
),
);
// The count is a bean, not a State: any widget or service can read and
// change it. The generated proxy notifies the listeners after every method.
@ChangeNotifierComponent()
class Counter {
int value = 0;
void increment() => value++;
}
// Lists the bean it needs in its type and gets it as `beans`.
class CounterPage extends SpringStatelessWidget<(Counter,)> {
const CounterPage({super.key});
@override
Widget build(BuildContext context) {
final (counter,) = beans;
return Scaffold(
body: const Center(child: CounterText()),
// Only calls a method, so a tap does not rebuild the page.
floatingActionButton: FloatingActionButton(
onPressed: counter.increment,
child: const Icon(Icons.add),
),
);
}
}
// Reads counter.value in build, so it rebuilds after every increment.
class CounterText extends SpringStatelessWidget<(Counter,)> {
const CounterText({super.key});
@override
Widget build(BuildContext context) {
final (counter,) = beans;
return Text('${counter.value}');
}
}
# lib/resources/application.yml
spring:
flutter:
app:
# No type: Scaffold needs a MaterialApp, and spring_boot_starter_flutter_material,
# the one design starter, makes the app one
title: Counter
theme:
seed-color: deepPurple
Running it
dart run build_runner watch # writes lib/spring_gen/main.spring.dart
flutter run
What happens at the start:
SpringApplicationWidgetshows the splash, reads the configuration files, adds the platform's and the build's profiles, loads the fonts among the assets and creates the beans.- It checks that every bean a Spring widget needs exists, so a missing bean fails the start instead of a later build.
- Once the context is ready it builds the app widget from
spring.flutter.app.*and the theme fromspring.flutter.theme.*, and showshome. - Logging is on from the start, in Spring Boot's format, to the console and to an in-memory
LogBufferbean:
INFO 82749 --- [main] spring_boot_dart.SpringApplication : The following 3 profiles are active: "desktop", "macos", "debug"
What is inside
Getting started:
- Configuration in a Flutter app: files, platform and build profiles, imports,
--dart-define, remote files. - SpringApplicationWidget: the root widget that starts the application.
- The app widget:
WidgetsApp,MaterialApporCupertinoAppfromspring.flutter.app.*. - Design libraries: an app without a design library, and Material or Cupertino with their starters.
Beans and state:
- Beans in widgets:
SpringStatelessWidget,SpringStatefulWidget,context.beanand@BuildContextAccess. - State beans:
@ChangeNotifierComponentand@NotifyListeners. - Messages and languages:
context.message, typedcontext.messagesand the app's locales. - The app lifecycle: lifecycle events and the pause in the background.
- Hot reload: when the context restarts and when it stays.
Themes:
- Themes: the whole look of the app in YAML, with its own pages for colors, typography, components, states, motion, backgrounds, images, loaders and Cupertino.
The start and tools:
- The splash and the start: stages, splash tasks, frames during the start, font warm-up, tracing.
- Keyboard shortcuts and taps: actions bound to keys or tap patterns in the configuration.
- The debug panel: logs, frames, configuration, beans, themes and the start of the running app.
- The frame meter: the frames a second the app really draws.
Content and files:
- MarkdownView: GitHub Markdown with the theme's colors, tables, code blocks and callouts.
- Assets and fonts:
asset:resources and fonts loaded from the assets. - Files of the app:
FileTemplatefor the app's own files. - SQLite databases: databases in the app's directory, on an isolate of their own.
Platforms:
- The desktop window: title, title bar and sizes of the window.
- The web: the page around the app, the page loader, the dev server, fonts, assets and WebAssembly.
- SEO: a page per address for search engines and link previews, the sitemap and llms.txt.
Reference:
- Testing:
springBootTestunderflutter_test, fakes and goldens. - All properties: every key of the starter.
- Differences from Spring: what works differently than in Spring Boot.
- Moving to 0.8: Flutter 3.50, the design starters and what changed for an app.
In Spring (Java)
Spring has no widget tree. The nearest thing to SpringApplicationWidget is the main method of a Spring Boot app:
@SpringBootApplication
class ShopApplication {
public static void main(String[] args) {
SpringApplication.run(ShopApplication.class, args);
}
}
Differences that matter:
@SpringBootApplication()goes on themainfunction, and the generator writes the application at build time. Runbuild_runnerafter you change annotations.- Widgets are not beans: Flutter creates them. They receive beans through their type (
SpringStatelessWidget<(Basket,)>) instead of injection. - The platform and the build mode are active profiles by themselves.
- The full list is on Differences from Spring.