# `native_splash`

| Package | Kind | Provides the role | Needs | Choose with |
| --- | --- | --- | --- | --- |
| [`smf_native_splash`](https://pub.dev/packages/smf_native_splash) | infrastructure | Splash screen | nothing | `-m native_splash` |

`native_splash` makes the screen that the system shows while the app starts with [flutter_native_splash](https://pub.dev/packages/flutter_native_splash), in place of the white screen of `flutter create`. All [flavors](https://doc.saymyframe.com/guides/flavors.md) of the app share the screen. To replace the images, see [App icon and splash screen](https://doc.saymyframe.com/guides/app-icon-and-splash.md).

## What it adds to the app

| In the app | What it is |
| --- | --- |
| `flutter_native_splash: ^2.4.8` in the dev dependencies | The tool. No code of the app imports it. |
| `assets/branding/splash_light.png` | 1152 by 1152 on a transparent background, the mark of Say My Frame in green, for the light mode of the device |
| `assets/branding/splash_dark.png` | 1152 by 1152 on a transparent background, the same mark in cream, for the dark mode |
| `flutter_native_splash.yaml` | How the tool makes the screen, with cream, `#F1F1E8`, behind the mark in the light mode and green, `#0F3326`, in the dark mode, and the same again under `android_12` |
| The section "Native splash" of the README | What the images show, where the colours are, and the command |

Whichever module provides it, the role adds the section "Splash screen" of the README. The app does not bundle the images.

In the [guide for coding agents](https://doc.saymyframe.com/guides/coding-agents.md) of the app, the role names the sources under "Splash screen". The module adds the command and what it rewrites.

## After generation

The module runs the tool once the app has its packages. A run in a terminal asks first, with Enter for yes:

```text
? Making the splash screen from assets/branding (dart run flutter_native_splash:create), for native_splash. Run it now? (Y/n)
```

A run without a terminal runs it too. When the tool fails, you still get the app, with a white launch screen, a warning and the command to run later.

Run it again after you change an image or `flutter_native_splash.yaml`, and commit what changed under `android/` and `ios/`:

```bash
dart run flutter_native_splash:create
```

The command rewrites `ios/Runner/Info.plist` with one more level of indentation.

Keep the mark of an image inside a circle of two thirds of its width, since Android 12 and later cut the rest. Keep `android_min_sdk` out of `flutter_native_splash.yaml`: with it, the tool leaves the launch background of Android below 12 as it is, and the screen there has no image.

A file `flutter_native_splash-<flavor>.yaml` does not give a flavor its own screen on iOS: the tool writes one, and the app keeps showing the screen of `flutter_native_splash.yaml`.

## Choosing it

`smf create` asks which module provides the splash screen, and the answer may be none. To choose it without the question:

```bash
smf create my_app -m native_splash
```