SpringApplicationWidget

SpringApplicationWidget is the root widget you pass to runApp. It starts the application: it reads the configuration files, creates the beans and runs the application's runners. Meanwhile it shows a splash screen. When the start fails, it shows a failure screen and logs the report. Once the context is ready, it gives it to every widget below.

Why

A Spring application starts asynchronously: files are read, fonts loaded, beans created. A Flutter app must draw something from its first frame. The widget joins the two: one widget in runApp, and the app shows its splash while the context starts, then the app itself. It also does what a Flutter app needs and a server does not: platform profiles, the app's lifecycle, hot reload, the desktop window.

Example

// lib/main.dart
import 'package:flutter/widgets.dart';
import 'package:spring_boot_starter_flutter/spring_boot_starter_flutter.dart';

import 'spring_gen/main.spring.dart';

@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    // A function, not the value: after a hot reload the widget calls it
    // again to get the new generated code.
    application: () => springApplication,
    // Optional: the theme's splash is used when there is no builder.
    splash: (context) => const ColoredBox(color: Color(0xFFFFFFFF)),
    failure: (context, error) => ErrorScreen(error),
    home: const BookListPage(),
  ),
);

Parameters

Parameter Default Meaning
application required Returns the application to run: () => springApplication, the variable the generator writes into main.spring.dart
home none The first page. The widget builds the app widget around it from spring.flutter.app.* (see The app widget)
child none Your own app widget (MaterialApp, ...) instead. Give home or child, not both
splash the theme's splash, else an empty box What is shown while the application starts. It wins over the theme's splash
failure a plain screen with the error (only a short note in release builds) What is shown when the start, or a restart after a hot reload, fails. The failure is logged either way
args none Command-line arguments (--name=value), read as properties; for desktop apps started with some
rerunRunnersOnReload false Whether ApplicationRunner and CommandLineRunner beans run again after a hot reload restarts the context

With neither home nor child, the app widget is built on the application's router: the RouterConfig<Object> bean that spring_boot_starter_flutter_navigation adds. A start without a router then fails with a message saying what to add.

What it does

Besides starting the application, the widget:

When the start fails

A bean that throws, a property with an invalid value or a missing bean stops the start. The widget then:

  1. logs the failure report, as a Spring Boot app does (the cause, the bean, the property, the valid values);
  2. shows failure, or its default screen: the error in debug and profile builds, a short note in release builds.

After a hot reload that fixed the problem, the widget starts the application anew.

// A failure screen in the app's style, with the error for developers.
SpringApplicationWidget(
  application: () => springApplication,
  failure: (context, error) => Directionality(
    textDirection: TextDirection.ltr,
    child: Center(child: Text(kReleaseMode ? 'Something went wrong.' : '$error')),
  ),
  home: const BookListPage(),
)

The failure screen is shown above any app widget, so it cannot use Theme.of or Localizations; give it what it needs, such as a Directionality.

Your own app widget

With child, you write the app widget yourself and the spring.flutter.app.* keys are not used. The themes still work: read them from the SpringThemes and ThemeSelection beans; a MaterialApp takes Material's ThemeData from the MaterialThemes bean of spring_boot_starter_flutter_material. Put the keyboard shortcuts in its builder (see Keyboard shortcuts):

// A MaterialApp: material_ui and spring_boot_starter_flutter_material.
SpringApplicationWidget(
  application: () => springApplication,
  child: Builder(
    builder: (context) => MaterialApp(
      title: 'NEON Books',
      theme: context.bean<MaterialThemes>().theme('light'),
      builder: (context, child) => KeyboardShortcutsScope(
        shortcuts: context.bean<KeyboardShortcuts>(),
        child: child!,
      ),
      home: const BookListPage(),
    ),
  ),
)

In tests

To test the start itself (the splash, a failed start, the platform profiles), pump SpringApplicationWidget as runApp does. The widget takes no bean overrides; for most widget tests, use springBootTest and a SpringScope instead (see Testing).

In Spring (Java)

Spring has no widget. The nearest thing is the main method of a Spring Boot app, SpringApplication.run(App.class, args). The failure report is the same one a Spring Boot app prints.

See also