Split Shared Code into Modules

A single huge shared module slows builds and blurs ownership. Splitting it into focused Gradle modules keeps the codebase fast and easy to reason about.

Each module compiles on its own and can be cached. Touch one feature and Gradle rebuilds only that module, not the entire shared codebase.

Two common cuts: by layer (core, data, domain) or by feature (orders, profile). Pick the seam that matches how your team actually works.

Shared utilities and base types live in a core module that everything can depend on. It depends on almost nothing, sitting at the bottom of the graph.

One module uses another by declaring it in build.gradle.kts. The feature module depends on core and domain, never the other way around.

Modules must form a one-way graph. If A depends on B and B on A, Gradle refuses to build. Avoiding cycles keeps the structure honest.

Use implementation to keep a dependency private to your module. Use api only when consumers genuinely need to see those transitive types.

Each KMP module gets its own commonMain, androidMain and iosMain. The split is structural, so platform code stays organised within every module.

Independent modules let Gradle compile in parallel and reuse caches across builds. More modules, drawn well, often means noticeably quicker feedback.

Module boundaries double as ownership lines. A team owns its feature module, sets its public surface, and changes it without stepping on others.

A module per file is chaos. Start coarse, split when a piece grows or many teams touch it. Let real pain, not theory, drive the next cut. 🙂

What rule must your module dependency graph obey?

You split shared code into focused modules, kept the dependency graph one-way, chose implementation over api, and let real needs guide each new split. 🎉