This page describes the breakdown of the steps involved to show a Flutter UI. Knowing this, you can make better, more informed decisions about when to pre-warm the Flutter engine, which operations are possible at which stage, and the latency and memory costs of those operations.

Android and iOS apps (the two supported platforms for integrating into existing apps), full Flutter apps, and add-to-app patterns have a similar sequence of conceptual loading steps when displaying the Flutter UI.

Flutter's engine runtime and your application's compiled Dart code are both bundled as shared libraries on Android and iOS. The first step of loading Flutter is to find those resources in your .apk/.ipa/.app (along with other Flutter assets such as images, fonts, and JIT code, if applicable).

This happens when you construct aFlutterEngine for the first time on bothAndroid andiOS APIs.

After it's found, the engine's shared libraries are memory loaded once per process.

OnAndroid, this also happens when theFlutterEngine is constructed because the JNI connectors need to reference the Flutter C++ library. OniOS, this happens when theFlutterEngine is first run, such as by runningrunWithEntrypoint:.

The Dart runtime is responsible for managing Dart memory and concurrency for your Dart code. In JIT mode, it's additionally responsible for compiling the Dart source code into machine code during runtime.

A single Dart runtime exists per application session on Android and iOS.

A one-time Dart VM start is done when constructing theFlutterEngine for the first time onAndroid and whenrunning a Dart entrypoint for the first time oniOS.

At this point, your Dart code'ssnapshot is also loaded into memory from your application's files.

This is a generic process that also occurs if you used theDart SDK directly, without the Flutter engine.

The Dart VM never shuts down after it's started.

After the Dart runtime is initialized, the Flutter engine's usage of the Dart runtime is the next step.

This is done by starting aDartIsolate in the Dart runtime. The isolate is Dart's container for memory and threads. A number ofauxiliary threads on the host platform are also created at this point to support the isolate, such as a thread for offloading GPU handling and another for image decoding.

One isolate exists perFlutterEngine instance, and multiple isolates can be hosted by the same Dart VM.

OnAndroid, this happens when you callDartExecutor.executeDartEntrypoint() on aFlutterEngine instance.

OniOS, this happens when you callrunWithEntrypoint: on aFlutterEngine.

At this point, your Dart code's selected entrypoint (themain() function of your Dart library'smain.dart file, by default) is executed. If you called the Flutter functionrunApp() in yourmain() function, then your Flutter app or your library's widget tree is also created and built. If you need to prevent certain functionalities from executing in your Flutter code, then theAppLifecycleState.detached enum value indicates that theFlutterEngine isn't attached to any UI components such as aFlutterViewController on iOS or aFlutterActivity on Android.

A standard, full Flutter app moves to reach this state as soon as the app is launched.

In an add-to-app scenario, this happens when you attach aFlutterEngine to a UI component such as by callingstartActivity() with anIntent built usingFlutterActivity.withCachedEngine() onAndroid. Or, by presenting aFlutterViewController initialized by usinginitWithEngine: nibName: bundle: oniOS.

This is also the case if a Flutter UI component was launched without pre-warming aFlutterEngine such as withFlutterActivity.createDefaultIntent() onAndroid, or withFlutterViewController initWithProject: nibName: bundle: oniOS. An implicitFlutterEngine is created in these cases.

Behind the scene, both platform's UI components provide theFlutterEngine with a rendering surface such as aSurface onAndroid or aCAEAGLLayer orCAMetalLayer oniOS.

At this point, theLayer tree generated by your Flutter program, per frame, is converted into OpenGL (or Vulkan or Metal) GPU instructions.