
# The splash and the start

While the application context starts, `SpringApplicationWidget` shows a splash: your own `splash:` builder, or the `splash` of the active theme (a background, a logo, a title and a loader that follows the start's progress). Behind it the configuration is read, the beans are created and the `SplashTask` beans run. When everything is ready, the splash plays its exit and the app shows.

This page covers how the start behaves: the stages, the tasks, the properties under `spring.flutter.splash`. How the splash looks (its loader, its logo, its exit) is the theme's: see [Loaders and the splash](themes/loaders.md).

## Why

A splash that freezes, or that disappears before the app is ready to draw its first screen, looks broken. The start knows its progress (the beans created, the runners called, the tasks done), so the splash can show real progress, keep moving while the beans are made, and hand over to the app without a jump. Work the first screen needs (a cache filled, the fonts of another script downloaded, the theme the user chose) runs before the app shows, not after.

## Example

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      splash:
        background: { color: $colors.surface-container-lowest }
        logo: { source: assets/images/logo.png, size: 96 }
        title: NEON Books
        loader: dots
        min-duration: 1.2s
        exit: { transition: 400ms ease-out }
      loaders:
        dots: { kind: dots, color: $colors.primary, size: 10, count: 3 }
    splash:
      tasks:
        timeout: 5s
```

```dart
// Fills the cache of the latest articles before the app shows.
@Component()
class WarmCache extends SplashTask {
  WarmCache(this.articles);

  final ArticleRepository articles;

  @override
  String get name => 'articles';

  @override
  Future<void> run(SplashTaskContext task) async {
    final ids = await articles.latest();
    for (final (i, id) in ids.indexed) {
      await articles.load(id);
      task.progress((i + 1) / ids.length); // the loader follows it
    }
  }
}
```

## The stages of the start

The start goes through these stages, in order (`SplashStage`):

| Stage | What happens |
|---|---|
| `page` | Web only: the browser opened the page and downloads the app's code. The page loader of `web/index.html` shows |
| `engine` | Web only: Flutter's engine starts. The page loader still shows |
| `splash` | Flutter drew its first frame: the splash is on screen (on the web the page loader is removed) |
| `starting` | The application starts: configuration read, beans created; the loader shows the progress |
| `tasks` | The `SplashTask` beans run; skipped when the app has none |
| `ready` | The context is ready: the loader plays its last phase, the splash waits for its `min-duration` |
| `exit` | The splash plays its exit |
| `app` | The splash is gone; the app shows |

On Android and iOS the system's launch screen shows before `splash`; on the desktop the window is held back until its size and title are set. Read the stages:

- in a loader, with `frame.stage` and tracks that follow a stage (see [Loaders](themes/loaders.md#tracks));
- as a bean: `SplashStages`, a `ValueListenable<SplashStage>` with `reached` (each stage with its time), `at(stage)` and `now`;
- as events: a `SplashStageEvent` (`stage`, `at`) per stage. Stages reached before the context existed are published when it is ready, in order.

```dart
// Sends the time of each stage to the app's analytics.
@Component()
class StartMetrics {
  StartMetrics(this.analytics);

  final Analytics analytics;

  @EventListener()
  void onStage(SplashStageEvent event) =>
      analytics.record('start.${event.stage.name}', event.at);
}
```

Times are milliseconds since the page started loading on the web, and since `SpringApplicationWidget` was created elsewhere.

## Splash tasks

A `SplashTask` bean runs once the beans exist, in the stage `tasks`, before `ready`. All run at the same time, and the loader's last share follows their progress.

- A task that does not report its progress counts when it ends.
- A task that fails is logged as a warning; the start goes on.
- A task still running after `timeout` goes on behind the app; the app shows.
- `@Order` (or `Ordered`) sets the order they begin.
- `SplashTaskContext.applicationContext` is the started context.

The starter has two tasks of its own: `themeChoiceRestore` shows the theme the user chose last time (see [Themes](themes/index.md)), and `textWarmUp` downloads fonts on the web when turned on (below).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.splash.tasks.enabled` | bool | `true` | Runs the `SplashTask` beans before the app is shown; `false`: none runs, and the beans take the whole loader |
| `spring.flutter.splash.tasks.timeout` | duration | `5s` | How long the splash waits for the tasks; one still running goes on behind the app |
| `spring.flutter.splash.tasks.share` | number, 0 to 1 | `0.2` | The share of the loader the tasks take, when the app has any |

## Frames during the start

Creating the beans is work on the UI thread: while a bean is made, Flutter draws no frame and the splash stands still. On the web every frame of the splash is drawn by that same thread, so a start of a few hundred milliseconds is a visible stop.

With `yield-frames`, the bean factory asks a pacer between two beans whether to wait. Under `frame-budget` of work it goes on; over it, it waits for the next frame, the splash draws, then the beans go on. With a budget of 8 ms and a frame of about 16 ms, the splash keeps about half the frames.

```yaml
spring:
  flutter:
    splash:
      yield-frames: true   # default: true on the web, false elsewhere
      frame-budget: 8ms
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.splash.yield-frames` | bool | `true` on the web, `false` elsewhere | Lets Flutter draw a frame between the beans while they are created, so the splash keeps moving. `false` turns the pacer off entirely |
| `spring.flutter.splash.frame-budget` | duration | `8ms` | The work between two frames when `yield-frames` is on |

Limits: a single bean that takes 200 ms still holds the thread for 200 ms, since the pacer only waits between beans; move such work out of the constructor. The start takes a little longer, by the frames it gives away.

## Fonts for the app's text

On the web, Flutter has no font for characters the app's fonts lack (Japanese, Chinese, Arabic, emoji). It downloads a Noto font for them the first time it lays them out, and lays out the text again after each piece. A language changed for the first time then stutters.

The `textWarmUp` task lays out every character of the app's text while the splash shows and waits until no font comes in any more. Each family is laid out with the theme's `font-family-fallback` behind it, as the app's text is: a character a font declared for the language has (`spring.flutter.fonts.families`) needs no download. The text comes from the files of `resources` and from each `TextWarmUpSource` bean. Only the characters count, each once: a large file costs its reading, not its layout.

```yaml
# lib/resources/application-web.yml
spring:
  flutter:
    splash:
      warm-up:
        text:
          enabled: true
          resources:
            - resources:messages*.properties
            - resources:content/**/*.ja.md
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.splash.warm-up.text.enabled` | bool | `false` | Lays out the characters of the app's text while the splash shows, so the fonts they need are downloaded before the app shows. Worth it on the web |
| `spring.flutter.splash.warm-up.text.resources` | list of location patterns | `resources:messages*.properties` | The files whose characters are laid out |
| `spring.flutter.splash.warm-up.text.first-font` | duration | `400ms` | No font downloaded in that time: none is needed, the warm-up ends |
| `spring.flutter.splash.warm-up.text.settle` | duration | `250ms` | After a font came in, how long without another before the warm-up ends |
| `spring.flutter.splash.warm-up.text.chunk` | number | `200` | How many characters are laid out in one frame, so the splash keeps moving on a phone |

## Tracing the start

Every app measures its start through Spring's `ApplicationStartup`: the `splashTrace` bean records a step per stage (`spring.flutter.splash.<stage>`) and each application event (`spring.event`, by its `eventName`). Each bean's creation is a step too with the [timeline](timeline.md) in the build, or with `spring.flutter.splash.trace: true`, which also logs the start. At `app`, one log line gives the stages and the five slowest beans:

```text
INFO SplashTrace: The start: page 40 ms, engine 910 ms, splash 1420 ms, starting 1450 ms, ready 1730 ms, exit 2950 ms, app 3350 ms. 42 beans; the slowest: spring.beans.instantiate beanName=catalogRepository 96 ms, ...
```

On the web the same steps are marks and measures of the browser's performance timeline (`spring:splash:<stage>`, one measure per bean), shown in the Performance tab next to the main thread's work.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.flutter.splash.trace` | bool | `false` | Measures the start: each stage and each bean's creation, logged at the end; on the web also as marks of the Performance tab |

The [debug panel](debug-panel.md) shows the stages of the running app in its Start tab.

## How the splash ends

- The loader gets the start's progress: the share of bean definitions created and runners called, then the tasks' share.
- When the context is ready, the loader's last phase plays, then the splash fades out over `exit.transition`, and not before `min-duration`. The app is built under it meanwhile.
- The widget's own `splash:` builder wins over the theme's splash. Without either, an empty box shows.
- With the system asking for less motion, each phase is at its end, nothing flickers, and the splash goes without a fade.

## The web page loader

While the browser downloads Flutter, the page shows a loader the generator writes into `web/index.html` from the same theme splash, so the page loader and the Flutter splash look the same and hand over without a jump. See [The page loader](../spring-core-dart-generator/flutter/page-loader.md) and [Loaders and the splash](themes/loaders.md).

## See also

- [Loaders and the splash](themes/loaders.md)
- [SpringApplicationWidget](application-widget.md)
- [The debug panel](debug-panel.md)
- [All properties](properties.md)
