The app widget

With home:, SpringApplicationWidget puts a SpringApp at the root: a WidgetsApp, or with a design starter a MaterialApp or CupertinoApp, set up by properties instead of code. Its type, title, debug banner and locales come from spring.flutter.app.*, its themes from spring.flutter.theme.*. The properties can differ per profile, so iPhones can get a CupertinoApp while the other platforms get a MaterialApp.

Why

An app widget is mostly settings: a title, the locales, a theme and a dark theme, observers. Written in Dart, they must be kept in step with the message files and the themes by hand. From properties, the locales follow the message files, the theme follows the theme files, and a platform or a build changes them by file name.

Example

Material on most platforms and Cupertino on iPhones: the app lists both design starters and their libraries. With two design starters it chooses the type, for every platform and again in the iOS profile (see The type when not set); an app with one design starter leaves type out.

# pubspec.yaml
dependencies:
  material_ui: ^1.11.0
  cupertino_ui: ^1.1.6
  spring_boot_starter_flutter_material: ^0.9.0
  spring_boot_starter_flutter_cupertino: ^0.9.0
# lib/resources/application.yml
spring:
  flutter:
    app:
      type: material
      title: NEON Books
      description: The bookshop of the NEON district.
      debug-banner: false
      locales: en, ja, pt_BR
# lib/resources/application-ios.yml: the iOS look on iPhones
spring:
  flutter:
    app:
      type: cupertino
@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    application: () => springApplication,
    home: const BookListPage(), // a MaterialApp, or a CupertinoApp on iOS
  ),
);

The properties

Key Type Default Meaning
spring.flutter.app.type text: widgets, material, cupertino, or the type of an app factory of your own not set: the one design starter's type (material, cupertino), else widgets; with several, required The app widget: WidgetsApp (this starter's own, no design library), MaterialApp (needs spring_boot_starter_flutter_material; needed by Scaffold, AppBar and the other Material widgets) or CupertinoApp (needs spring_boot_starter_flutter_cupertino). See App factories
spring.flutter.app.title text empty The app's name for the OS: the task switcher, the browser tab. The web build also writes it into web/index.html (<title>) and web/manifest.json (name, short_name)
spring.flutter.app.description text none What the app is, in a sentence. Not used at run time: the web build writes it into web/index.html (<meta name="description">) and web/manifest.json
spring.flutter.app.debug-banner true, false true Flutter's DEBUG banner in debug builds
spring.flutter.app.locales comma-separated language tags (en, pt_BR, zh_Hant_TW) the languages of the message files The locales the app supports

Write locales as one comma-separated value, also in YAML (locales: en, ja). The app widget reads it as a single value, so a YAML list ([en, ja]) is not seen; the locales then come from the message files.

The type when not set

spring.flutter.app.type need not be set. As Spring Boot deduces spring.main.web-application-type from the class path, the application's starters decide:

The application has The app is
no design starter widgets, a WidgetsApp
one design starter: spring_boot_starter_flutter_material or spring_boot_starter_flutter_cupertino material or cupertino
one SpringAppFactory bean of its own type (ocean, see App factories) that type
app factories of several types, both design starters for instance none: the start fails and asks for the property

With several, the failure report names the property and the types:

Invalid argument(s) (spring.flutter.app.type): not set, and the application has app widgets of several types: cupertino, material. Choose one, for every platform or in a profile of each (spring.flutter.app.type=cupertino in application-ios.properties)

Set, the property always wins: widgets keeps a WidgetsApp although a design starter came in through another package, and an app that sets its type is not changed by a starter it adds.

Locales

By default the app supports the languages it has texts for: messages.properties counts as English, and each messages_<locale>.properties adds its locale (messages_ja adds ja, messages_pt_BR adds pt_BR). So the app's locales and context.message agree. With other files than messages*.properties, set spring.messages.basename as one comma-separated value with / as the separator (i18n/messages,i18n/errors), and the starter looks for the locales of those files.

Flutter's own translations for the app type (the texts of its widgets, in every language) are added by the type's app factory (SpringAppFactory.localizationsDelegates): GlobalWidgetsLocalizations for widgets; the Material starter's factory adds Material's (GlobalMaterialLocalizations), the Cupertino starter's Cupertino's (GlobalCupertinoLocalizations). flutter_localizations comes with the starter. See Messages and languages.

The theme

The theme shown is the one the ThemeSelection bean picks. widgets gets the theme's text style and color. With the Material starter, material gets the Material ThemeData of the theme shown (and its dark counterpart for system); with the Cupertino starter, cupertino gets the CupertinoThemeData. A theme picked at run time, or loaded from a server, shows at once. A SpringTheme above the app gives the theme to the app's own widgets. See Themes.

Every NavigatorObserver bean becomes an observer of the app's navigator, in @Order:

// Logs every screen the user opens.
@Component()
@Log()
class ScreenLog extends NavigatorObserver {
  @override
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) =>
      log.info('Opened ${route.settings.name}');
}

FlutterAppCustomizer

What no property covers is changed by a FlutterAppCustomizer bean: a builder, keyboard shortcuts, the scrollBehavior, the app's own localization delegates. Each one gets the FlutterAppSettings once, before the app widget is first built, in @Order:

// The app's own translations, and text that never grows past 130 %.
@Component()
class AppLocalizations implements FlutterAppCustomizer {
  @override
  void customize(FlutterAppSettings app) {
    app.localizationsDelegates.add(LegalTerms.delegate);
    app.builder = (context, child) => MediaQuery.withClampedTextScaling(
      maxScaleFactor: 1.3,
      child: child!,
    );
  }
}

The fields of FlutterAppSettings:

Field From Meaning
type spring.flutter.app.type, or when not set the type the starters decide on The type of the app factory that builds the app widget, a String (widgets, material, cupertino)
title spring.flutter.app.title The app's name for the OS
debugShowCheckedModeBanner spring.flutter.app.debug-banner The DEBUG banner
supportedLocales spring.flutter.app.locales or the message files The app's locales
localizationsDelegates the app factory's (Flutter's for the type) Add the app's own here
navigatorObservers the NavigatorObserver beans The navigator's observers
builder null Wraps the navigator, like MaterialApp.builder
scrollBehavior null The app's scroll behavior (not used by a WidgetsApp)
shortcuts null The app's keyboard shortcuts in Flutter's form; for actions in the configuration, see Keyboard shortcuts

The starter uses customizers itself: the keyboard shortcuts and the debug panel are installed around the navigator that way. Spring Boot (Java) customizes its web server the same way, with a WebServerFactoryCustomizer bean.

Routes

home is the first page, and the app navigates with Navigator. Without home, SpringApp builds the router form of the app widget (WidgetsApp.router, or MaterialApp.router and CupertinoApp.router of the design starters) on the application's RouterConfig<Object> bean: the one spring_boot_starter_flutter_navigation adds, or the app's own.

App factories

spring.flutter.app.type is a text: the type of a SpringAppFactory bean, which builds the app widget. Types are compared without case.

Type App factory From
widgets WidgetsAppFactory spring_boot_starter_flutter (its own)
material MaterialAppFactory (bean materialAppFactory) spring_boot_starter_flutter_material
cupertino CupertinoAppFactory (bean cupertinoAppFactory) spring_boot_starter_flutter_cupertino

A design of your own is one more bean:

// An app widget of the company's own design system.
@Component()
class OceanAppFactory implements SpringAppFactory {
  @override
  String get type => 'ocean';

  @override
  List<LocalizationsDelegate<Object?>> get localizationsDelegates =>
      const [GlobalWidgetsLocalizations.delegate];

  @override
  Widget build(BuildContext context, SpringAppRequest app) =>
      OceanApp(title: app.settings.title, home: app.home);
}

spring.flutter.app.type: ocean then builds an OceanApp; without a design starter in the application, the type need not be set, as the one factory of its own decides. The SpringAppRequest has the settings, the themes, the theme selection, the theme shown, the builder to pass on as it is, and home or the router. See Design libraries.

Checked at the start

The settings are made once per context, when the application starts. An invalid value (debug-banner=maybe) fails the start with the failure report, naming the property. So does a type no app factory has: material or cupertino without its starter names the starter to add (the app widget of type material is built by spring_boot_starter_flutter_material: add it to the dependencies (this application has: widgets)), any other type lists the known ones (type=swing: one of: widgets).

With your own app widget

With SpringApplicationWidget(child: ...) you write your own app widget, and these keys are not used. In widget tests, put a SpringApp under a SpringScope to get the app widget of the properties (see Testing).

See also