flutter-native-splash-engineering

Flutter Native Splash Engineering

Treat flutter_native_splash as a native/Web resource generator, not an application loading-screen framework. Optimize the startup path separately from the appearance of the OS-to-Flutter transition.

Start with evidence

Before changing code or generated resources:

1. Inspect pubspec.yaml, pubspec.lock, Flutter/Dart constraints, target platforms, flavors, and build pipelines.
2. Identify the locked flutter_native_splash version and whether runtime preserve()/remove() APIs are imported.
3. Find every splash configuration file, generation command, generated-resource ownership rule, preserve/remove call, and startup owner.
4. Inspect source asset formats, pixel dimensions, transparency, file sizes, dark variants, branding, and platform overrides.
5. Audit all synchronous work and awaited initialization before runApp and the first stable Flutter frame.
6. Inspect the first Flutter frame, theme/system bars, and layout for visual continuity with each native/Web splash.
7. Separate Android pre-12, Android 12+, iOS/iPad, and Web behavior.

The bundled guide was validated against flutter_native_splash 2.4.8 on 2026-08-11. Use the installed package README, API, and changelog as the source of truth when versions differ, especially for configuration keys, Android 12+ behavior, preserve/remove, flavors, Web output, and toolchain requirements.

Preserve these invariants

• Support only the package's declared Android, iOS, and Web targets; do not fabricate macOS, Windows, or Linux support.
• Treat Android 12+ as a separate system splash with icon masking and restricted layout; do not reuse a pre-12 full-screen design blindly.
• Keep native splash content static and compile-time generated.
• Do not use app-internal theme preferences to choose native dark mode; native appearance follows platform/system resources available before Flutter runs.
• Do not use GIF, Lottie, or unsupported native animation hacks. Continue rich animation in Flutter after the first frame.
• Minimize work before runApp and the first frame.
• Never add Future.delayed merely to keep branding visible.
• Use preserve() only for a small, essential prerequisite and assign exactly one owner to remove().
• Move long, dynamic, network-dependent, retryable, progressive, or interactive startup work into a Flutter startup/loading screen.
• Match the first Flutter frame's background, logo placement, system bars, and theme closely enough to avoid flashes and jumps where practical.
• Regenerate resources after configuration or source-asset changes; hot reload and hot restart do not regenerate launch resources.
• Do not run flutter clean after every edit. Use it only when targeted regeneration and full rebuild still leave stale artifacts.
• Treat generated native/Web files as generated state unless the repository has an explicit manual-merge ownership strategy.
• Keep one CI strategy: either commit deterministic generated files or generate them deterministically in CI; do not mix uncontrolled approaches.
• Use flavor/brand-specific compile-time resources; do not runtime-switch native splash branding.
• Prefer flat colors and lightweight correctly sized raster assets over huge full-screen images where the design permits.
• Measure actual startup in profile/release-like cold and warm launches; splash duration in debug is not a performance metric.