# Add a Native Splash Screen to a Flutter App

Yes. An agent generates native launch screens for Android, iOS and web with flutter_native_splash, holds them until your app has initialised, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-splash-screen/flutter/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads what each platform shows today before the first Flutter frame. In an app like simplezhli/flutter_deer, `pubspec.yaml` is on Dart 3.4 and Flutter 3.19 or newer with no `flutter_native_splash`. On Android, `res/drawable/launch_background.xml` is a layer list with only `@color/bg_color` and a commented-out bitmap, `values/colors.xml` sets that colour to white and `values-night/colors.xml` to `#18191A`, and `values-v27/styles.xml` keeps `windowLayoutInDisplayCutoutMode` set to `shortEdges` on `LaunchTheme`; there is no `values-v31`, so phones on Android 12 and later show the system's icon splash instead. On iOS, `LaunchScreen.storyboard` centres a `LaunchImage` image set on the system background colour. The app also has its own `lib/home/splash_page.dart`, a `SplashPage` that waits for `SpUtil.getInstance()` and `Device.initDeviceInfo()` and then either shows the three `app_start_*.webp` guide pages or goes to login, and `main.dart` calls `WidgetsFlutterBinding.ensureInitialized()` inside `handleError`.

It adds `flutter_native_splash` as a dev dependency and writes its settings in a `flutter_native_splash.yaml` at the repository root rather than inside the already long `pubspec.yaml`: `color` white and `color_dark` `#18191A` to match the existing `bg_color` values, `image` set to `assets/images/logo.png`, and an `android_12` section with the same image and colours plus an `icon_background_color`, which is what Android 12's splash API actually draws. It then runs `dart run flutter_native_splash:create`, which rewrites `launch_background.xml` with the bitmap, writes resized drawables from mdpi to xxxhdpi, adds the `values-v31` and `values-night-v31` styles, edits the iOS storyboard and `Info.plist`, and writes a `web/splash/` folder with the CSS that `web/index.html` now includes.

Because the generator overwrites `styles.xml`, the agent diffs the Android resources afterwards and puts the `shortEdges` cutout mode back on the v27 theme, keeps `NormalTheme` as it was, and checks `AndroidManifest.xml` still points `LaunchTheme` at the activity. In Dart, `main.dart` keeps the `WidgetsBinding` it already creates and passes it to `FlutterNativeSplash.preserve`, and `SplashPage` calls `FlutterNativeSplash.remove()` once the two initialisers have finished, so the native splash holds until the app knows whether to show the guide or the login instead of flashing a blank frame between the two.

It installs the Flutter SDK in the sandbox, runs `flutter pub get`, `flutter analyze` against the repository's strict `analysis_options.yaml`, `flutter test` for `test/widget_test.dart` and the other unit tests, and `flutter build web` to show the web splash assets end up in the build. It does not build the Android or iOS apps, because that needs the Android SDK and Xcode, and the pull request says which platforms were built and which were only generated and inspected.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a native splash screen to this Flutter app with flutter_native_splash. Read pubspec.yaml, lib/main.dart, lib/home/splash_page.dart and the Android res/values, res/drawable and iOS LaunchScreen files first. Configure light and dark background colours that match the existing launch colours, use the app logo as the image, include an android_12 section, and generate the assets. Restore any Android theme attributes the generator overwrites, preserve the native splash in main.dart and remove it from the in-app splash page once initialisation has finished. Run flutter analyze, flutter test and a web build, and open a pull request that lists every generated file by platform.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that adds `flutter_native_splash.yaml`, changes `pubspec.yaml`, `lib/main.dart` and `lib/home/splash_page.dart`, and carries the generated files: the Android drawables and `values-v31` styles, the edited `launch_background.xml`, the iOS storyboard, image set and `Info.plist` change, and the `web/splash/` folder with the `web/index.html` edit. The description groups the files by platform, names the theme attribute it restored after generation, and pastes the `flutter analyze`, `flutter test` and `flutter build web` output.

The run's record keeps the generator's own output, so a reviewer can see which files `flutter_native_splash:create` wrote and compare that against the diff rather than trusting the description.

Before merging, a reviewer runs the app on an Android 12 device and an iPhone, since the sandbox can generate and inspect the native assets but cannot launch either platform, and decides whether the logo and icon background colour match the brand on the Android 12 splash, which crops the image into a circle.

## Run it on every Linear issue labelled mobile-ux

In the console, an automation in the Project that has the repository, with a `linear` trigger on `linear.issue.labeled` and `labels` set to `mobile-ux`, starts one run per issue with the issue as its context after the prompt; the saved prompt is the whole instruction, and the trigger fills in no placeholder. A later issue that asks for a branding image under the logo, a splash per flavour, or a different dark colour is one more run on top of the `flutter_native_splash.yaml` this pull request adds.

From your own tracker, a handler sends one `POST /o/{org}/sessions` with this body, the repository in `resources` and a `request_id` that is a UUID v5 of the issue id, so a repeated delivery returns the run already started. With a `webhook_url` on the key, Rush posts `run.completed` with the `session_url` when the pull request is up.

## Why run it on Rush?

A splash screen is three platforms of generated files plus two lines of Dart, and the generator is happy to overwrite a hand-edited theme or leave a blank frame between the native splash and the app's own. The agent reads the existing launch resources, writes settings that match them, runs the generator and then checks what it changed, and ties the removal to the app's real initialisation instead of the first frame.

The sandbox is a computer of its own where the Flutter SDK is installed for the run, and every command, including the generator's output and the analyzer's, stays in the run's record. Several apps or flavours can be done at once in separate sandboxes, each ending in its own pull request.

## Frequently asked questions

### Will the in-app splash page with the guide still work?

Yes. `SplashPage` keeps its guide swiper and its login redirect; the only change is a `FlutterNativeSplash.remove()` call once `SpUtil` and the device info are ready. Until then the native splash stays up, so the user sees the logo rather than a white or dark frame.

### Why does Android 12 need its own section?

Android 12 and later ignore `launch_background.xml` and draw their own splash from the app icon and a window background. The `android_12` block tells the generator to write `values-v31` styles with your image and colours, so those phones show the same logo as older ones instead of the default launcher icon.

### Does the generator touch files I edited by hand?

It rewrites `styles.xml`, `launch_background.xml`, the iOS storyboard and `web/index.html`. The agent diffs the result and restores what the generator dropped, such as the `shortEdges` cutout mode on the v27 launch theme, and the pull request names each restored attribute.

### Can I change the colours later without redoing this?

Yes. Edit `flutter_native_splash.yaml` and run `dart run flutter_native_splash:create` again; `dart run flutter_native_splash:remove` puts Flutter's default launch files back. The configuration file is the source of truth, and the generated files are committed so a checkout builds without running the tool.

## More Flutter jobs

- [Replace Deprecated Flutter APIs Across an App and Make the Analyzer Catch the Next Ones](https://getrush.ai/run/fix-deprecated-apis/flutter/)
- [Fix Flutter Errors from Sentry Alerts](https://getrush.ai/run/fix-sentry-errors/flutter/)
- [Review Pull Requests on a Flutter App](https://getrush.ai/run/review-pull-requests/flutter/)

## The same job on other stacks

- [Add a Splash Screen to an Electron App](https://getrush.ai/run/add-splash-screen/electron/)

## More jobs like this: Turn a Linear label into a PR

- [Add a SQLite Database to a Reflex App](https://getrush.ai/run/add-sqlite-database/reflex/)
- [Add Server-Side Rendering to a Lit Component](https://getrush.ai/run/add-ssr/lit/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
