
# 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

```dart
// 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](app-widget.md)) |
| `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](../spring-boot-starter-flutter-navigation/index.md) adds. A start without a router then fails with a message saying what to add.

## What it does

Besides starting the application, the widget:

- adds the platform's profiles (`android` and `mobile`, `web`, `macos` and `desktop`, ...) and the build's (`debug`, `profile`, `release`); see [Configuration](configuration.md);
- does not read the OS environment variables unless a build defines `spring.flutter.scan-os-environment=true`;
- loads the font files among the app's assets (see [Assets and fonts](assets-and-fonts.md));
- shows the active theme's splash, which follows the start's progress, and runs the `SplashTask` beans before the app shows (see [The splash and the start](splash.md));
- checks that every bean a Spring widget needs exists, so a missing one fails the start instead of a later build;
- sets the desktop window from `spring.flutter.desktop.window.*` before the first frame (see [The desktop window](desktop-window.md));
- puts SQLite databases into the app's directory (see [SQLite databases](sqlite.md));
- publishes the app's lifecycle and pauses the context in the background (see [The app lifecycle](lifecycle.md));
- restarts the context after a hot reload that changed beans (see [Hot reload](hot-reload.md));
- closes the context when it is removed from the tree: `@PreDestroy` methods run and lifecycle beans stop.

## 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.

```dart
// 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](../spring-boot-starter-flutter-material/index.md). Put the keyboard shortcuts in its `builder` (see [Keyboard shortcuts](shortcuts.md)):

```dart
// 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](testing.md)).

## 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

- [The app widget](app-widget.md)
- [The splash and the start](splash.md)
- [Hot reload](hot-reload.md)
- [Configuration in a Flutter app](configuration.md)
