Migrating a Jetpack Compose app to Kotlin Multiplatform

Checklist for a potential Kotlin Multiplatform migration

The main hurdles for a potential KMP migration are Java and Android Views. If your project is already written in Kotlin and uses Jetpack Compose for the UI, it lowers the complexity of a migration considerably.

Here is a general checklist of what preparations you should consider before migrating a project or a module:

1. Convert or isolate Java code

2. Check your Android/JVM-only dependencies

3. Catch up with modularization technical debt

4. Migrate to Compose

Steps to make an app multiplatform

After the initial preparations and evaluations are done, the general process is:

1. Migrate to multiplatform libraries

2. Transition your business logic to KMP.

   1. Start with a module that has the fewest other modules depending on it.

   2. Migrate it to the KMP module structure and migrate to using multiplatform libraries.

   3. Pick the next module in the dependency tree and repeat the process.

3. Transition your UI code to Compose Multiplatform. When all of your business logic is already multiplatform, transitioning to Compose Multiplatform becomes relatively straightforward. For Jetcaster, we show incremental migration by migrating screen by screen/ We also show how to adjust the navigation graph when some screens have been migrated and some have not.

To simplify the example, we removed Android-specific Glance, TV, and wearable targets from the start since they don't interact with multiplatform code anyway and won't need to be migrated.

Migrate to multiplatform libraries

There are a couple of libraries that most of the app's functionality relies on. We can transition their usage to be KMP-compatible before configuring the modules for multiplatform support:

• Migrate from the ROME tools parser to the multiplatform RSS Parser. This requires accounting for differences between the APIs, one of which is how they handle dates.

• Migrate from Dagger/Hilt to Koin 4 throughout the entire app, including the Android-only entry point module mobile. This requires rewriting the dependency injection logic according to the Koin approach, but code outside *.di packages remains largely unaffected.

  When you migrate away from Hilt, make sure to clear /build directories to avoid compilation errors in previously generated Hilt code.

• Upgrade to Coil 3 from Coil 2. Again, relatively little code was modified.

• Migrate from JUnit to kotlin-test. This concerns all modules with tests, but thanks to the kotlin-test compatibility, there are very few changes needed to implement the migration.

Migrating the business logic

Once the primary dependencies are multiplatform, we can choose a module to start with the migration. It can be useful to build a dependency graph of the modules in your project. An AI agent like Junie can easily help with that. For Jetcaster, the simplified graph of module dependencies looked like this:

This suggests the following sequence, for example:

1. :core:data

2. :core:data-testing

3. :core:domain

4. :core:domain-testing

5. :core:designsystem — while it doesn't have module dependencies, this is a UI helper module, so we tackle it only when we're ready to move UI code into a shared module.

Migrating to multiplatform UI

When all the :core logic is multiplatform, you can start moving UI to common code as well. Once again, since we're aiming for full migration, we're not adding the iOS target yet, just making sure that the Android app works with Compose parts placed in common code.

To visualize the logic that we'll follow, here is a simplified diagram that represents relationships between Jetcaster screens:

Firstly, we created a shared UI module, for the UI code we're going to make common.

To demonstrate migrating the UI gradually, we'll move screen by screen. Each step will end in a commit that contains the app in a working state, a little closer to a fully shared UI.

Guided by the screens diagram above, we started with the podcast details screen:

1. The migrated screen will work with the Compose theme still in the Android module. What we need to do:

   1. Update the ViewModel and the corresponding DI code.

   2. Update the resources and resource accessors. While the multiplatform resources library is closely aligned with the Android experience, there are some notable differences that need to be addressed:

      • There are slight differences in how resource files are handled. For example, the resource directory needs to be called composeResources instead of res, and @android:color usages in Android XML files need to be replaced with color hex-codes. See the documentation on multiplatform resources to learn more.

      • The generated class with resource accessors is called Res (as opposed to R on Android). After you've moved and adjusted the resource files, regenerate the accessors and replace the imports for each resource in your UI code.

2. Migrate the Compose theme. We also provide stubs for platform-specific implementations of color schemes.

3. Continue with the home screen:

   1. Migrate the ViewModel.

   2. Move code to commonMain in the shared UI module.

   3. Move and adjust references to resources.

4. To demonstrate another way to atomize the migration, we partially migrated navigation. We can combine screens in common code with an Android native screen. The PlayerScreen is still located in the mobile module, and is included in navigation only for the Android entry point. It is injected into the overarching multiplatform navigation.

5. Finish by moving everything that is left over:

   • Move the rest of navigation over to common code (resulting commit).

   • Migrate the last screen, PlayerScreen, to Compose Multiplatform (resulting commit).

Now that all the UI code has been made common, we can use it to quickly create apps for other platforms.

Optional: Add a JVM entry point

This optional step helps to:

• Show how little effort it takes to create a desktop app out of an Android app that's been made completely multiplatform.

• Showcase Compose Hot Reload, which is currently only supported for desktop targets, as a tool for quickly iterating on a Compose UI.

With all the UI code shared, adding a new entry point for a desktop JVM app is a matter of creating a main() function and integrating it with the DI framework.

Add an iOS entry point

The iOS entry point requires an iOS project that is linked with the KMP code.

Creating and embedding an iOS app in a KMP project is covered in the Make your app multiplatform tutorial.

In the iOS app, we need to connect the Swift UI code with our Compose Multiplatform code. We do that by adding a function that returns a UIViewController with the embedded JetcasterApp composable to the iOS app.

Run the app

In the final state of the migrated app, there are run configurations for the initial Android module (mobile) and the new iOS app. You can run the desktop app from the corresponding main.kt file. Run them both to see the way shared UI works on all platforms!

Final summary

In this migration, we followed general steps for turning a pure Android app into a Kotlin Multiplatform app:

• Transition to multiplatform dependencies, or rewrite the code where it's not possible.

• Transform Android modules usable on other platforms into multiplatform modules, one by one.

• Create a shared UI module for Compose Multiplatform code, and transition to shared UI code, screen by screen.

• Create entry points for other platforms.

This sequence is not set in stone. It's possible to start with entry points for other platforms, and gradually build the foundation under them until they work. In the Jetcaster example, we chose a clearer sequence of changes that is easy to follow step by step.

If you have any feedback on the guide or demonstrated solutions, create an issue in YouTrack.