Publishing KMP Apps to Google Play, the App Store, Desktop and the Web

The shared code is compiled into a different artifact per target, and the artifact decides everything downstream.

Two consequences follow. First, versioning must be coordinated, otherwise the same release is "1.4.0" on one store and "1.3.9" on another. Second, the shared module is only as releasable as its weakest platform: a Kotlin change that compiles for Android can still break the iOS archive or the Wasm bundle, so every release candidate should be built on every target. See iOS Integration Options for how the shared framework reaches the Xcode project.

Every store wants two values: a human-readable version name shown to users, and a monotonically increasing build number the store uses to order uploads. They go by different names on each platform.

Keep the numbers in one place, gradle.properties in the repository root, and let each platform read them.

The Android and desktop modules read the properties directly. For iOS, a small Gradle task writes an .xcconfig file that the Xcode project includes, so Xcode never holds a second copy of the numbers.

See Gradle docs — Writing custom tasks.

In Xcode, set iosApp/Configuration/Config.xcconfig to #include "Version.xcconfig" and leave the target’s version fields as $(MARKETING_VERSION) and $(CURRENT_PROJECT_VERSION). The same values can be read at run time, for example on the About screen of the SwiftUI version of TrailMate.

See Apple Developer — Build settings reference and Apple: Xcode Projects and Previews.

A common mistake is bumping only versionName. Play rejects an upload whose versionCode is not greater than every previous one, and App Store Connect rejects a build whose build number was already used for that version. Derive the build number from the CI run number or a git commit count if manual bumping becomes error-prone.

Under AGP 9, the Android application cannot be combined with the KMP plugin in one module: it lives in its own androidApp module and consumes sharedUI and sharedLogic like any other dependency (see The Android Target and AGP 9). That is good news for releasing, because the release configuration of androidApp is the ordinary Android release configuration, fully described in Android: Building, Signing and Preparing a Release. This section shows only the multiplatform-specific parts.

See Android Developers — Configure build variants and Android Developers — Sign your app.

Build the bundle with ./gradlew :androidApp:bundleRelease; the result is androidApp/build/outputs/bundle/release/androidApp-release.aab. Play distributes an optimized APK per device configuration from it, which is why Play requires the bundle format for new apps (see Android: Publishing on Google Play for the Play Console steps: store listing, Data safety form, testing tracks, staged rollout).

The iOS release is built by Xcode, not by Gradle. Gradle’s role ends when the shared Kotlin framework is linked for iosArm64 (the embedAndSignAppleFrameworkForXcode task runs from an Xcode build phase), after which Xcode signs, archives and uploads exactly as for a pure Swift app. The Apple-side details are in Apple: Membership, Signing, Capabilities and Info.plist and Apple: App Store Connect, TestFlight and App Review; the KMP-specific points follow.

A crash report from an iOS device contains addresses, not names. Symbolication maps those addresses back to function names and lines using the app’s dSYM (debug symbols) file, matched by build UUID. For Kotlin code the process is the same as for Swift, because Kotlin/Native compiles to LLVM and produces ordinary DWARF debug information.

Two things must be true for readable Kotlin frames:

You can check that a dSYM matches a binary and symbolicate a single address by hand.

See Apple Developer — Building your app to include debugging information and Apple Developer — Acquiring crash reports and diagnostic logs.

Apple’s Organizer symbolicates crashes automatically when the dSYM was uploaded. Third-party crash reporters (Firebase Crashlytics, Sentry) need their own upload step, normally a build phase or CI step that sends the dSYMs folder. A Kotlin exception that escapes into Swift terminates the app as an uncaught Objective-C-visible crash; how exceptions cross the boundary, and why @Throws matters, is explained in Objective-C and Swift Interop, and debugging tools for the native side are in Kotlin/Native Memory, Performance and Debugging. Reading the reports themselves is covered in Apple: Logging, MetricKit, Crash Reports and Organizer.

The equivalent artifacts for the other targets are the R8 mapping.txt on Android (see above) and, on the web, the source maps that the Kotlin/Wasm build emits next to the .wasm file; keep them out of the public folder if you do not want to expose your sources.

Apple requires a privacy manifest, a property-list file named PrivacyInfo.xcprivacy, for apps that use required reason APIs (file timestamps, disk space, system boot time, user defaults and active keyboards) or that collect data. It also asks that commonly used third-party SDKs ship their own manifest. App Store Connect warns, and later rejects, uploads that use such APIs without declaring a reason. In a KMP app there are two sources of API usage: your Swift code, and the Kotlin code compiled into the framework, including its libraries (Ktor’s Darwin engine, DataStore, SQLDelight’s native driver, Coil).

The approach that works regardless of how the framework is linked:

See Kotlin docs — Privacy manifest for Kotlin Multiplatform and Apple Developer — Privacy manifest files.

The reason codes above are examples: CA92.1 means the app reads and writes its own user defaults and C617.1 means it accesses timestamps of files inside the app container. Choose the codes that match what your app and its libraries actually do, from the list in Apple Developer — Describing use of required reason API. Declaring a reason that is untrue is a policy violation, so check the documentation of each library rather than copying a manifest from another project. On Android the equivalent disclosure is the Play Data safety form, and for the web it is your own privacy policy and cookie banner; see Apple: Security and Privacy.

Desktop apps built with Compose Multiplatform are packaged by the Compose Gradle plugin through the JDK’s jpackage tool: a self-contained installer with a trimmed runtime, so users need no Java. The nativeDistributions block, the formats table, ProGuard release builds and macOS signing and notarization are described in detail in Compose Multiplatform for Desktop; this section covers the release workflow.

See Kotlin docs — Native distributions and local execution.

Release decisions that are specific to desktop:

See Kotlin docs — Native distributions and local execution.

The Wasm web app is a folder of static files: index.html, a JavaScript loader, one or more .wasm files and resources. There is no server component, and no review process. Build it with the production distribution task and upload the folder; the full GitHub Pages workflow and the compatibility build with a JavaScript fallback for browsers without WasmGC are in Web Targets: Kotlin/Wasm, Kotlin/JS and Compose for Web. Remember that Kotlin/Wasm and Compose Multiplatform for web are Beta, so state this in release notes and keep an HTML fallback for unsupported browsers.

See Kotlin docs — Publish your application.

Hosting needs to get three things right. The server must send Content-Type: application/wasm for .wasm files so that browsers can compile them while streaming. Compression (gzip or Brotli) matters because Wasm bundles with Compose are several megabytes. Caching must separate the entry point, which changes with every release, from the content-hashed assets.

See nginx — ngx_http_core_module.

Because the web has no store-side rollback, keep the previous build in a dated folder and switch a symbolic link on deploy. Rolling back is then a one-line change.

Use this table as a template for the release issue of each version. Items that apply to every target come first.