Generate native splash screens for Android and iOS from a single Kotlin Gradle DSL, then keep them on screen at runtime until your app is ready to draw — built for Compose Multiplatform / KMP projects.

Android	iOS

The project ships two pieces:

Together they replace the manual ritual of hand-rolling per-density PNGs, Android 12 windowSplashScreen* themes, iOS launch storyboards, and UILaunchStoryboardName plumbing — for every flavor of every variant.

• Quick start
• Features
• Installation
  • 1. Apply the Gradle plugin
  • 2. Add the runtime library (optional)
• Usage
  • Generate the assets
  • Defer the first frame at runtime
• Customization
  • Full DSL surface
  • AGP integration
  • AGP 9 split structure
  • iOS multi-flavor Xcode wiring
  • Source-set fallback (no AGP)
  • Runtime knobs
• Troubleshooting
• Tasks reference
• Compatibility
• License
• Contributing
• Acknowledgements

The Gradle plugin is the only required piece. Apply it to your KMP module (the one with kotlin { } / commonMain — composeApp, or shared on the AGP 9 split structure):

// composeApp/build.gradle.kts
plugins {
    id("ly.com.tahaben.kmp-native-splash") version "1.0.0"
}

kmpNativeSplash {
    color = "#42a5f5"
    image = "splash_assets/logo.png" // 4× asset; path resolves against the module dir
}

Generate the native Android + iOS splash assets:

./gradlew generateNativeSplash

That's it — when AGP is applied the assets are wired into your Android build automatically. To also keep the splash on screen until your app is ready to draw, add the optional runtime library and call NativeSplash.preserve() / remove() — see Usage.

• Single source of truth — colors, foreground image, branding, and the Android 12 icon in one kmpNativeSplash { … } block.
• Native output — per-density Android drawable-* / values-* and iOS Assets.xcassets + LaunchScreen.storyboard.
• Dark mode — colorDark / imageDark generate a parallel drawable-night-* / dark-appearance tree.
• Android 12+ splash API — drawable-*-v31 icons + values-v31/styles.xml (animated icon, icon background, branding image).
• Flavors — flavor("dev") { … } produces per-flavor Android resources and per-flavor iOS storyboards / imagesets.
• AGP & AGP 9 ready — auto-wires generated resources into AGP variants, and auto-detects the Android application module in the AGP 9 split structure.
• iOS Xcode auto-wiring (opt-in) — patches project.pbxproj + Info.plist for per-flavor launch storyboards; idempotent.
• Runtime control — NativeSplash.preserve() / remove() from common code to hold the splash until you're ready (animated fade on iOS).

Plugin vs. library — what you actually need. The Gradle plugin is the only required piece: apply it to generate the native splash assets at build time. The runtime library (ly.com.tahaben:kmp-native-splash) is optional — add it only if you want to control the splash from common code via NativeSplash.preserve() / NativeSplash.remove() (keep it on screen, then dismiss it, once your app is ready to draw). Generation alone needs no library dependency.

Apply it to the KMP module — the one with the kotlin { } multiplatform block and commonMain. That is composeApp in the classic single-module structure, or shared in the AGP 9 split structure (where the Android application module lives in a separate :androidApp). The plugin auto-detects where the Android application module is; see AGP 9 split structure.

// composeApp/build.gradle.kts  (or shared/build.gradle.kts on AGP 9)
plugins {
    id("ly.com.tahaben.kmp-native-splash") version "1.0.0"
}

Skip this step entirely if you only need the generated assets. Add it when you want to call NativeSplash.preserve() / NativeSplash.remove() from common code:

// composeApp/build.gradle.kts  (or shared/build.gradle.kts on AGP 9)
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("ly.com.tahaben:kmp-native-splash:1.0.0")
        }
    }
}

In the AGP 9 split structure, also add it to the :androidApp module's dependencies — the Android Activity that calls NativeSplash.installSplashScreen(this) / preserve() lives there, so it needs the dependency directly (it isn't pulled in via the shared module):

// androidApp/build.gradle.kts  (AGP 9 split structure)
dependencies {
    implementation("ly.com.tahaben:kmp-native-splash:1.0.0")
}

The runtime is published for androidTarget, iosX64, iosArm64, iosSimulatorArm64, jvm (covers Compose Desktop's jvm("desktop")), js, wasmJs, and linuxX64. JVM, Linux, and the web targets ship no-op actuals so commonMain calls compile and link everywhere.

Release notes & version history: GitHub Releases.

// composeApp/build.gradle.kts
kmpNativeSplash {
    color = "#42a5f5"
    image = "splash_assets/logo.png" // supply a 4× asset — path resolves against the module directory
}

Run once:

./gradlew generateNativeSplash

Generated outputs:

build/generated/kmpnativesplash/default/res/   (Android — auto-fed to AGP if applied)
└── drawable-mdpi/   drawable-hdpi/   …   drawable-xxxhdpi/
    drawable-v21/    drawable-night/  drawable-*-v31/
    values/styles.xml + values-v31/styles.xml

iosApp/iosApp/
├── Assets.xcassets/LaunchImage.imageset/
├── Assets.xcassets/LaunchBackground.imageset/
└── Base.lproj/LaunchScreen.storyboard

Per-platform tasks are also exposed: generateAndroidSplash, generateIosSplash, plus generate<Flavor>NativeSplash once flavors are declared.

// Android: MainActivity.kt
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        NativeSplash.installSplashScreen(this)   // wires AndroidX SplashScreen
        super.onCreate(savedInstanceState)
        NativeSplash.preserve()                  // keep it on screen
        lifecycleScope.launch {
            initializeApp()
            NativeSplash.remove()                // dismiss
        }
    }
}

On iOS you can preserve from either side of the bridge. Kotlin (iOS source set) is the simplest path — no framework export required:

// iosMain: MainViewController.kt
import androidx.compose.ui.window.ComposeUIViewController

fun MainViewController() = ComposeUIViewController {
    NativeSplash.preserve()
    App()
}

Swift works too, but the runtime must be re-exposed in the produced framework's public header. In your composeApp/build.gradle.kts, declare the dependency as api and add export(...) on every iOS framework binary:

kotlin {
    listOf(iosX64(), iosArm64(), iosSimulatorArm64()).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "ComposeApp"
            export("ly.com.tahaben:kmp-native-splash:1.0.0")
        }
    }
    sourceSets {
        commonMain.dependencies {
            api("ly.com.tahaben:kmp-native-splash:1.0.0")
        }
    }
}

Then preserve from your SwiftUI entry point. .onAppear on the WindowGroup root fires once the key window exists, which is what NativeSplash needs:

// iosApp.swift

import SwiftUI
import ComposeApp

@main
struct iOSApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onAppear {
                    NativeSplash.shared.preserve()
                }
        }
    }
}

Note: without the api + export(...) wiring above, NativeSplash will not appear in the ComposeApp framework's Swift surface — import ComposeApp will succeed but the symbol won't resolve. The Kotlin-side approach above sidesteps this entirely.

In Compose Multiplatform commonMain code, dismiss the splash once you're ready to draw:

@Composable
fun App() {
    LaunchedEffect(Unit) {
        warmCachesAndPreload()
        NativeSplash.remove()
    }
    // … your UI …
}

kmpNativeSplash {
    // ── Project coordinates ────────────────────────────────────────────────
    // AGP 9 split only; omit for the classic single-module structure (auto-detected).
    // Gradle project path of the standalone com.android.application module.
    androidModule = ":androidApp"
    useGeneratedSourceSet = true // AGP path; flip to false for source-set writes

    android {
        // Path strings. Relative paths resolve against this module's directory.
        resRoot = "src"                                       // default: "src"
        manifest = "src/androidMain/AndroidManifest.xml"      // default: "src/androidMain/AndroidManifest.xml"
    }
    ios {
        // Path to the iOS project directory, relative to this module (default: "../iosApp")
        projectPath = "../iosApp"
        // Name of the Xcode target for the iOS app (default: "iosApp")
        targetName = "iosApp"
        // iOS app source folder. Defaults to `<projectPath>/<targetName>` — set explicitly
        // only if your layout deviates.
        // appDir = "../iosApp/iosApp"
    }

    // ── Default variant ────────────────────────────────────────────────────
    // Image paths are plain strings. Relative paths resolve against the module
    // directory; absolute paths are used as-is.
    color = "#42a5f5"
    colorDark = "#042a49"
    image = "splash_assets/logo.png"         // 4× source
    imageDark = "splash_assets/logo_dark.png"
    backgroundImage = "splash_assets/bg.png" // mutually exclusive with `color`
    fullscreen = false

    // ── Platform-specific overrides ────────────────────────────────────────
    android {
        gravity = "center"            // any android:gravity value
        screenOrientation = "portrait"
    }
    ios {
        contentMode = "scaleAspectFit"
        infoPlistFiles.addAll("Info-Debug.plist", "Info-Release.plist")
    }

    // ── Branding image (rendered in addition to the foreground) ────────────
    branding {
        image = "splash_assets/brand.png"
        mode = BrandingMode.BOTTOM    // BOTTOM | BOTTOM_LEFT | BOTTOM_RIGHT
        bottomPadding = 24
    }

    // ── Android 12+ SplashScreen API ───────────────────────────────────────
    android12 {
        color = "#42a5f5"
        image = "splash_assets/a12_logo.png"
        iconBackgroundColor = "#111111"
        brandingImage = "splash_assets/brand.png"
    }

    // ── Platform toggles ───────────────────────────────────────────────────
    platforms {
        android = true
        ios = true
    }

    // ── Per-flavor overrides (delta against the default variant) ───────────
    flavor("dev") {
        color = "#222222"
        image = "splash_assets/logo_dev.png"
    }
    flavor("prod") {
        image = "splash_assets/logo_prod.png"
        android12 { image = "splash_assets/a12_prod.png" }
    }
}

Per-flavor generateDevAndroidSplash, generateDevIosSplash, generateDevNativeSplash are registered automatically.

When com.android.application, com.android.library, or com.android.kotlin.multiplatform.library is applied, the plugin hooks androidComponents.onVariants:

android {
    productFlavors {
        create("dev")
        create("prod")
    }
}
kmpNativeSplash {
    flavor("dev") { color = "#ffffff" }
    flavor("prod") { color = "#42a5f5" }
}

Yields generateDevDebugAndroidSplash, generateProdReleaseAndroidSplash, etc., each wired into the matching processVariantAndroidResources via variant.sources.res.addGeneratedSourceDirectory. No sourceSets {} edits required.

AGP 9 splits the classic single composeApp module: shared/generated code stays in the KMP module (shared, applying com.android.kotlin.multiplatform.library), while the Android application + productFlavors move to a standalone :androidApp module (com.android.application). Apply this plugin to the KMP module in both layouts — it resolves where the Android application module is.

// shared/build.gradle.kts
kmpNativeSplash {
    // Standard AGP 9 layout (single :androidApp) needs nothing — auto-detected.
    // Set this only for non-standard layouts (multiple app modules / custom names):
    androidModule = ":androidApp"
    color = "#42a5f5"
    image = "splash_assets/logo.png" // read from shared/, written into androidApp/
}

androidApp/src/main/res/    ← default variant   (classic composeApp: src/androidMain/res/)
androidApp/src/dev/res/     ← flavor "dev"
androidApp/src/prod/res/    ← flavor "prod"

kmpNativeSplash {
    ios {
        autoWireXcodeFlavors = true
        // Both default to the stock KMP layout; override only if yours deviates.
        // The `.xcodeproj` path is derived as `<projectPath>/<targetName>.xcodeproj`.
        projectPath = "../iosApp"
        targetName = "iosApp"
    }
    flavor("dev") { /* … */ }
    flavor("prod") { /* … */ }
}

All edits are idempotent — re-running produces zero new entries. Commit your Xcode project before enabling this.

Prerequisite — per-flavor build configurations + schemes (the plugin does not create these). iOS has no product flavors. A per-flavor launch screen is selected by the Xcode build configuration that is active when the app runs. A stock KMP iosApp ships only Debug and Release, so without setup every flavor shows the default LaunchScreen. You must, in Xcode (or via a flavor plugin like KMP-Flavorizr), have per-flavor build configurations + a scheme per flavor that builds with them. The plugin maps a configuration to its storyboard by the flavor token in its name (the build-type token never wins), so all of these resolve correctly: Debug-dev / Release-dev, devDebug / prodRelease / devProfile (KMP-Flavorizr / xcconfig style), Dev Debug, PROD_RELEASE. It only patches configurations that already exist — it does not create them.

Per-flavor launch screen not switching at runtime? See Troubleshooting.

When the project doesn't apply AGP, or when useGeneratedSourceSet = false:

kmpNativeSplash { useGeneratedSourceSet = false }

Output flips to the on-disk source-set path:

src/androidMain/res/   ← default variant
src/dev/res/           ← flavor "dev"
src/prod/res/          ← flavor "prod"

These paths are relative to the resolved Android module. In the classic single-module structure that's the applied module (src/androidMain/res/). In the AGP 9 split it's :androidApp, a standalone com.android.application module, so the default variant uses the standard Android source set instead — androidApp/src/main/res/ (flavors stay androidApp/src/<flavor>/res/). See AGP 9 split structure.

// iOS-only: point at a different storyboard if you don't use the plugin-owned one
NativeSplash.storyboardName = "MyCustomLaunchScreen"

// Android-only: hook the SplashScreen exit animation
NativeSplash.installSplashScreen(this) { splashScreenViewProvider ->
    splashScreenViewProvider.view.animate()
        .alpha(0f).setDuration(300)
        .withEndAction { splashScreenViewProvider.remove() }
        .start()
}

The per-flavor LaunchScreen<Flavor>.storyboard files generate and look correct in Xcode, but the app always launches with the default. Causes, in order of likelihood:

1. Xcode wiring is opt-in and disabled. Check the Gradle log: if > Task …:wireXcodeFlavors SKIPPED (or the iOS task warns that Xcode is NOT wired), then kmpNativeSplash.ios.autoWireXcodeFlavors is false (the default — it patches project.pbxproj, so it's off until you opt in). Enable it:

   kmpNativeSplash { ios { autoWireXcodeFlavors = true } }

   Commit your Xcode project first. Without this, the per-flavor storyboards are generated but never connected to any build configuration.
2. No per-flavor build configurations (see the prerequisite under iOS multi-flavor Xcode wiring). With wiring enabled, ./gradlew generateNativeSplash logs each config '<name>' → <storyboard> mapping and warns loudly when every configuration resolved to the default. If you only see Debug/Release, add the per-flavor configs.
3. GENERATE_INFOPLIST_FILE = YES — the on-disk Info.plist edit is ignored by Xcode. The plugin also routes INFOPLIST_KEY_UILaunchStoryboardName through $(LAUNCH_SCREEN_STORYBOARD); ensure that key exists in the target's build settings.
4. iOS launch-screen cache — iOS caches the launch screen aggressively. After the fix, delete the app from the simulator/device (or erase the simulator) and rebuild.

Built and tested on Kotlin 2.3.0, AGP 8.13.0, JDK 17, androidx-core-splashscreen 1.2.0.

Released under the Apache License 2.0 — see LICENSE.

SPDX-License-Identifier: Apache-2.0

Issues, bug reports, and PRs are welcome.

1. Fork and branch off main.
2. Build and test:

   ./gradlew build
   ./gradlew :plugin:test :library:allTests

3. Open a PR against main; CI (build + multi-target test matrix) runs automatically.

For larger changes, open an issue first to discuss the approach.

Inspired by flutter_native_splash.