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:
- in a loader, with
frame.stageand tracks that follow a stage (see Loaders); - as a bean:
SplashStages, aValueListenable<SplashStage>withreached(each stage with its time),at(stage)andnow; - as events: a
SplashStageEvent(stage,at) per stage. Stages reached before the context existed are published when it is ready, in order.
// 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
timeoutgoes on behind the app; the app shows. @Order(orOrdered) sets the order they begin.SplashTaskContext.applicationContextis the started context.
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 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 beforemin-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 and Loaders and the splash.