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.

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

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

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

The starter has two tasks of its own: themeChoiceRestore shows the theme the user chose last time (see Themes), 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.

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.

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

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 shows the stages of the running app in its Start tab.

How the splash ends

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 and Loaders and the splash.

See also