Kotlin Multiplatform starter guide
Where to start
Learn about Kotlin Multiplatform (KMP) and Compose Multiplatform (CMP): What they are, their advantages, and use cases.
Try KMP out on a sample project to see how it's organized and how it runs on different platforms.
Learn KMP basics
The basics include:
Understand how a KMP / CMP project is organized. This covers:
Common and platform-specific code in a shared module.
Targeted platform declarations.
Adding a dependency to a KMP project.
For a practical example of multiplatform and platform-specific dependency organization, see our sample.
The tutorial that leads to the final state of that sample is available in the documentation.
If you are already familiar with KMP, make sure you're up to date with the recommended project structure for an average project. It takes into account how the release of Android Gradle plugin 9.0 affected the requirements for a KMP project and covers:
Module structure (independent app modules with shared code modules used as libraries).
Creating new app modules and transitioning from an older structure used with AGP 8.
Suggested video on project structure recorded by a JetBrains developer advocate.
Share code
There are different ways to share code in a KMP project, with some platform specifics:
The basic examples of calling common code from app modules are covered in onboarding tutorials:
How to access platform-specific APIs:
Use multiplatform libraries when possible.
Use the
expect/actualmechanism when no suitable multiplatform library is available.
While calling shared Kotlin from Android Kotlin is relatively straightforward, iOS interoperability takes some getting to know it:
In general, the less interop, the better, so for a smoother experience we recommend relying on Compose Multiplatform to build the bulk of your UI for all platforms.
Learn how to integrate your shared code with the iOS app (all samples referenced in this doc have examples of iOS integration set up).
Check out the sample and tutorial that includes making Kotlin coroutines work with iOS.
See the guide on using existing SPM packages in your KMP iOS app.
Read the in-depth explanation of calling Swift / ObjC from Kotlin and vice versa.
Learn about the more straightforward Swift export approach (currently in Alpha).
Discover the ecosystem
A comprehensive catalog of multiplatform libraries is available at klibs.io:
Most popular cases are already covered with robust solutions, usually with available alternatives: SQLDelight and Room for databases, Ktor and OkHttp for networking, Coil for image loading, and so on.
App samples built to use multiplatform libraries for most popular use cases are available:
SQLDelight / Ktor / kotlinx-serialization / Koin with the corresponding tutorial.
The multiplatform Jetcaster app converted from the original Android sample.
Create a KMP library
If you decide to pack your shared code into a multiplatform library, check out these documentation pages:
Tutorials on publishing artifacts to Maven Central and npm
Publish the artifacts
Read the general article on publishing KMP apps.
Don't forget about the privacy manifest required by the Apple App Store.
Using AI for KMP development
Before you start
Use the free Junie access
Junie is a JetBrains AI agent. For Shipaton participants, JetBrains offers free access to the EAP version of the Junie CLI agent. You can also use your Junie agent through the AI chat feature in IntelliJ IDEs.
Set up and commit AGENTS.md
AI agents heavily rely on AGENTS.md files when exploring an unfamiliar codebase, so accurate and comprehensive context can noticeably improve the quality of their insights and generated code. For example, simply noting that your project uses Kotlin Multiplatform can help avoid a lot of cross-platform issues.
To learn about the format and see examples, check out the AGENTS.md website.
Configure useful MCP servers
These MCP servers can be useful for an AI agent building an app in the KMP context:
The klibs.io server helps to look for a suitable multiplatform library.
The Compose Hot Reload server allows the agent to quickly iterate on the UI.
Build features
Use planning mode
For larger tasks and distributed work, most agents support a planning mode which can help break down the task and generate a clear step-by-step instruction that you can verify before the code generation starts in earnest.
Spending time to review and refine the results of the work done in planning mode usually produces significantly better results for implementing:
user-facing features from scratch,
architectural changes,
library integrations,
large refactorings.
Validate AI-generated changes
On top of the general AI non-determinism, Kotlin Multiplatform introduces multifaceted context that is hard to cover comprehensively. For example, it is common for changes to be implemented well and working for one platform and breaking another.
To address this, it's a good idea to define specific acceptance criteria:
Run target-specific tests after introducing changes, whenever such tests are available.
Verify that all configured KMP targets successfully build before considering a task complete.
Review the implementation for platform-specific APIs leaking into common code: this can lead agents (and humans) to use these APIs in later stages.
Use Kotlin AI skills
The Kotlin team builds and maintains AI skills aimed at solving Kotlin-specific problems. See the skills repository and install the skills for your agent.
Use Swift Package Manager to integrate native iOS libraries
For iOS functionality that does not yet have a multiplatform library supporting it, you may need to integrate native iOS libraries. We recommend using SwiftPM packages and the corresponding DSL for configuring such dependencies.
The Kotlin team maintains an AI skill aimed at CocoaPods to SwiftPM migration, which can also be useful for setting up SwiftPM integration from scratch.
Set up agent orchestration
JetBrains Air offers agent orchestration which can help speed up work by coordinating multiple agents working on different parts of the project simultaneously.
Iterate on UI
Use Figma to generate UI designs and Compose code
The Figma MCP server can help with converting designs into Compose code.
For generating UI designs from scratch, consider Google Stitch or Figma Make.
Use Gemini CLI as the agent for Compose UI tasks
We have seen consistently good results when generating Compose code with Google's model, including models in the Flash family. It offers a good balance of generation speed, token consumption, and UI quality.
Use Compose Hot Reload to iterate on UI
Compose Hot Reload enables almost real-time UI updates that reflect changes you — or your agent — make in the Compose code.
To help agents work with UI, you can add the Compose Hot Reload MCP server to your agent configuration. It enables the agent to trigger reloads directly, take screenshots, and even interact with the UI.
Learning resources catalog
All of the mentioned resources, along with more in-depth guides and third-party content, are catalogued on the Learning resources page.