r/KotlinMultiplatform • • 3d ago

One Compose Multiplatform codebase on Android, iPhone, iPad and the browser: what tripped me up shipping a word game

I have just finished taking a small word game, WordEke, from an Android-only Kotlin and Jetpack Compose app to the same code running on Android, iOS, iPadOS and the web. It is in both stores and playable in a browser, so here are the parts that were not in the tutorials. Kotlin 2.3.21, Compose Multiplatform 1.11.1.

How it is laid out

•     core: a Kotlin Multiplatform module with no Android dependencies. All the game logic is in commonMain: board generation, dictionaries, scoring, the tap-selection state machine. Its tests run on the JVM with no emulator, which was the reason for the split long before iOS came up.

•     shared: the whole UI in Compose Multiplatform, targeting android, iosArm64, iosSimulatorArm64, wasmJs and js.

•     What the UI needs from a platform is one interface plus a handful of expect functions. Billing, sharing, the camera and notifications sit behind it.

•     The iOS app is an Xcode shell with a single SwiftUI file that shows the shared view controller.

1. Kotlin/Wasm does not run on an iPad that stops at iPadOS 17

Kotlin/Wasm needs WebAssembly garbage collection and exception handling. Safari gained them in 18.2, and every browser on an iPhone or iPad is Safari underneath. Several iPads from 2017 and 2018 end at iPadOS 17, so for their owners the page sat on "Loading" forever, with no error. Two players reported it before I understood why.

The fix was to build the game twice from the same source. I added a js target beside wasmJs and moved the web code into a source set the two share. Nothing in it had to change: the js() interop, promises and the settings storage compile for both. The page validates a small probe module, loads the Wasm build where that passes, and the JavaScript build elsewhere, and gives a failed Wasm start one try at JavaScript. Both builds keep their data in the same localStorage, so an iPad that later updates keeps its games.

Cost: one more script of about 4 MB, compressed to about 1 MB, that current browsers never download. The JavaScript build still uses Skia's .wasm, which only requires 2017-era WebAssembly.

2. Long-lived caching and fixed file names nearly bricked returning players

My server caches .js for years. The generated script had a fixed name and referred to .wasm files named by content. A deploy that replaced the folder deleted the old .wasm files, so a phone running the previous script requested files that no longer existed and hung. Reloading did not help, because the stale script was the thing being cached.

Two changes: the scripts are now named by content as well, and a deploy adds to the folder instead of replacing it, with old builds pruned after a month. That is also why I did not use Compose's own compatibility distribution for the Wasm and JavaScript pair: it does the same job but assigns fixed names to the scripts.

3. Lowering the iOS minimum

I had set the minimum to iOS 18.5 because that made a linker warning go away. Skia's ICU data object inside the framework is built for 18.5, and with a lower target the linker says it "was built for newer iOS version than being linked". I never tested a lower target, so the high minimum only hid the warning. Dropping to 17.0 brought it back.

The object holds data, not code. The build succeeds, the tests pass and the app runs on current simulators. But the current Xcode won't download any iOS 17 simulator for me, so the app on iOS 17 itself is still untested: a real device on 17 will be the test, and a refurbished 2018 iPad is on its way for exactly that. If text, dates or prices come out wrong there, the ICU data is my first suspect.

4. iPad is a one-way door

Once a released version supports iPad, Apple does not allow a later update to drop support for it, and the first submission requires 13-inch iPad screenshots. On iPad, the window can also be resized, so the layout has to cope with sizes a phone never has.

What I would do again

•     Keep the game logic in a pure Kotlin module from day one. Moving it to commonMain was the easy part because it never knew about Android.

•     Put every platform need behind one interface early. Each new target then has an obvious list of things to implement.

•     Test the web build on the oldest Safari you can find, not only in Chromium.

The game is free with no ads, and the browser version needs no install or account, so you can see the result at https://wordeke.com (the store links are there too).

Happy to answer questions about any of it. I would particularly like to hear from anyone who has found a cleaner way to serve Wasm with a JavaScript fallback.

Updates and feedback on the game itself: r/wordeke

6 Upvotes

1 comment sorted by

1

u/MKevin3 3d ago

Nice read, thanks for writing it up.

Reminds me that Android is a bit friendlier when it comes to older emulators. Previous project I worked on, not KMP, had to support back to 5.1.1 due to hardware being stuck on that version.

We did our KMP app with Android and IOS in mind first but were able to add Desktop support, sans a few features like Firebase notifications. Starting out forcing yourself to support multiple platforms is the key to KMP / CMP.

I was really happy how well things work on all platforms. The desktop even has a very responsive UI support as we support phone and tablet layouts with master / detail panels.

We had no need for a web version so I did have to handle that hassle.