Revolutionizing Kotlin Multiplatform: Introducing a Streamlined Project Structure

Overview of the Updated Kotlin Multiplatform Project Structure

JetBrains has unveiled a significant overhaul of the default project structure for Kotlin Multiplatform (KMP) projects. This update is designed to clarify each module’s responsibility, align more closely with conventions from other build systems and frameworks, and accommodate changes in Android Gradle Plugin (AGP) 9.0. The new structure will be automatically applied to projects created using JetBrains tools, official documentation, and sample repositories going forward.

Revolutionizing Kotlin Multiplatform: Introducing a Streamlined Project Structure — Source: blog.jetbrains.com

Already live in the KMP wizard (both in IntelliJ IDEA with the Kotlin Multiplatform plugin and on kmp.jetbrains.com), this change aims to reduce confusion by separating shared code from platform-specific application logic. Samples like kotlinconf-app, KMP-App-Template, and RSS Reader now reflect the new layout and can serve as references for developers.

What Has Changed in the Default Project Structure?

Old Structure: A Single, Overloaded Module

Previously, most KMP projects relied on a single composeApp Gradle module. This module served dual purposes: it acted as a Kotlin Multiplatform library containing shared code, and it also functioned as an application for one or more platforms—housing entry points and platform-specific configuration. In the Project view, this looked like a monolithic block where code, resources, and packaging details for all platforms were intertwined.

New Structure: Clear Separation of Concerns

The revamped default structure introduces a shared module with a singular, unambiguous responsibility: it is a Kotlin Multiplatform library containing all shared logic. On top of that, dedicated application modules are created for each platform where a runnable app is built. For example, androidApp, desktopApp, and webApp now live as separate folders, each with its own entry points and platform-specific configurations.

In the Project view, the new hierarchy is far more modular:

shared – contains common code (business logic, data models, networking, etc.)
androidApp – Android-specific application with its own entry point
desktopApp – Desktop application module (if applicable)
webApp – Web application module (if applicable)
iosApp – Already separated, remains as an Xcode project consuming the shared library

Why These Changes Were Made

Reducing Complexity and Role Overlap

In the old composeApp module, responsibilities were blurred. It contained a massive amount of configuration—including packaging rules for every target platform—making it difficult for developers to understand which part defined the library and which part defined the application. Separating these roles into distinct modules simplifies maintenance and clarifies intent.

Uniformity Across Platform Configurations

When a developer decided not to share UI (e.g., using SwiftUI for iOS), the old structure required adding an extra shared module alongside composeApp. That was a drastic structural change introduced only in certain configurations. The new model always has a shared module, so the architecture remains consistent whether or not UI is shared across platforms. This reduces cognitive overhead and streamlines project setup.

Addressing iOS Asymmetry

Previously, iOS applications were already in a separate iosApp folder (because they require an Xcode project to consume the shared code), while all other platform applications were crammed into composeApp. This asymmetry was confusing and broke the uniform layout. With the new structure, every platform gets its own application module, making iOS a natural part of the pattern rather than an exception.

Compliance with Android Gradle Plugin 9.0

AGP 9.0 introduces a critical requirement: the entry point of an Android application must reside in a module separate from any shared or library code. It no longer allows applying the Android application Gradle plugin inside a multiplatform module. The new default structure adheres to this rule by placing the Android app in its own androidApp module, ensuring compatibility with future Android build toolchains.

How to Migrate Existing Projects

Developers can adopt the new structure by manually refactoring their projects. The key steps involve:

Extracting shared code from the old composeApp module into a new shared module.
Creating separate application modules for each target platform that previously lived inside composeApp (e.g., Android, Desktop, Web).
Updating dependency declarations so that application modules depend on the shared module.
Adjusting entry points, manifest files, and Gradle configurations to reflect the new module layout.

For a comprehensive migration guide, refer to the official Kotlin Multiplatform documentation.

Tooling and IDE Support

To fully leverage AGP 9.0 support within IntelliJ IDEA, update to version 2026.1.2 or newer, and ensure you have the latest version of the Android plugin installed. The KMP wizard in the IDE and on the web already generates projects with the new structure, so starting fresh is straightforward.

Conclusion

The new default project structure for Kotlin Multiplatform marks a major step toward clarity, consistency, and future-proofing. By clearly separating shared library code from platform-specific applications, JetBrains reduces complexity, aligns with industry conventions, and prepares the ecosystem for the next generation of Android build tools. Developers starting new KMP projects will benefit immediately, while existing projects can migrate to enjoy these advantages. With sample projects already updated and documentation following shortly, the community has everything needed to embrace this improved architecture.