Forem: Tom Horvat

Self-Referential Generics in Kotlin: When Type Safety Requires Talking to Yourself

Tom Horvat — Wed, 01 Apr 2026 23:09:37 +0000

Kotlin's type system is expressive enough to let you write code that is simultaneously statically typed, runtime validated, and ergonomic at the call site. That combination usually requires some machinery — and understanding why the machinery exists, rather than just how to copy it, is the difference between architecture and cargo-culting.

For reference, we will use the RandomPokemon repo.

The BaseViewModel in this codebase is a clean example of a pattern where self-referential generics, reified type parameters, and a sealed class hierarchy solve a real problem at a boundary where compile-time types naturally blur.

An implementation like this enforces a single, standardized way to consume use case output that makes type mismatches observable before they reach production.

The Problem at the UI/Domain Boundary

ViewModels sit at a boundary between two distinct type worlds. The domain layer produces ResultState — a sealed class that carries either a message, an error, or a payload typed as Any?:

sealed class ResultState {
    data class Running(val message: String? = null) : ResultState()
    data class Error(val error: Throwable? = null) : ResultState()
    data class Complete<out O>(val data: O?) : ResultState()
}

The UseCase<in O> abstraction wraps this in a StateFlow<ResultState?>, where O is the expected output type:

abstract class UseCase<in O>(private val logger: Logger? = null) {

    abstract val name: String    
    private val _state = MutableStateFlow<ResultState?>(null)
    val state: StateFlow<ResultState?> = _state

    protected fun running(message: String? = null) {
        logger?.d("Running $name: $message")
        _state.value = ResultState.Running(message = message)
    }

    protected fun Throwable?.update() {
        logger?.e(this ?: Throwable(), "Error in $name")
        _state.value = ResultState.Error(error = this)
    }

    protected fun O?.update() {
        logger?.d("Completed $name: $this")
        _state.value = ResultState.Complete<O>(data = this)
    }
    // ...
}

The variance declarations here are intentional and worth noting: Complete<out O> is covariant because ResultState produces values of type O (you read .data out of it), while UseCase<in O> is contravariant because a use case consumes O to update its state (via protected fun O?.update()) — it never hands O back to a caller. If you try to implement this pattern and swap the variance annotations, the compiler will tell you exactly where the flow of data breaks.

Notice that O is a contravariant input type parameter (used only in protected fun O?.update()), but the exposed StateFlow is typed to ResultState? — the O is erased at the boundary. By the time the ViewModel receives useCase.state, it has no compile-time knowledge of what type is inside ResultState.Complete.

This is inherent to the architecture. Use cases communicate via a shared ResultState channel, which must be typed to the sealed class rather than each use case's specific output type. You can't parameterize StateFlow over a generic that varies per use case if the ViewModel holds multiple use cases simultaneously.

So, where do you recover type safety, and at what cost?

The ViewModel's Generic Parameter

BaseViewModel is generic over its own state model:

open class BaseViewModel<M : ViewModelState>(initialState: M) : ViewModel(), KoinComponent {
    private val _state: MutableStateFlow<M> = MutableStateFlow(initialState)
    val state: StateFlow<M> = _state.asStateFlow()

    protected fun updateState(transform: (M) -> M) {
        _state.update(transform)
    }
}

The M : ViewModelState bound means the ViewModel's own state (the UI state model) is typed. This is the self-referential part: HomeViewModel extends BaseViewModel<HomeState>, binding M to HomeState. The updateState lambda then gives subclasses a type-safe transformation — transform: (HomeState) -> HomeState — rather than an untyped mutation.

This is a well-understood pattern. The interesting part is how collectUseCase operates across both generic contexts — and what it enforces.

Two Generics, One Function

protected inline fun <reified O> UseCase<O>.collectUseCase(
    crossinline onRunning: (String?) -> Unit = {},
    crossinline onError: (Throwable?) -> Unit = { e -> onUseCaseError(e) },
    crossinline onDone: suspend (O?) -> Unit = {}
) = viewModelScope.launch {
    this@collectUseCase.state.collect {
        it?.let {
            it.parse<O>(
                onError = { e -> onError(e) },
                onRunning = { m -> onRunning(m) },
            ) { result -> onDone(result) }
        }
    }
}

This extension function on UseCase<O> is declared inside BaseViewModel<M>. It introduces its own generic parameter O (reified), independent of the class-level M. The function has access to viewModelScope (from the enclosing BaseViewModel context) while O is the expected output type of the specific use case being collected.

The call site looks like this:

getPokemon.collectUseCase<PokemonDetails>(
    onRunning = { updateState { it.copy(loading = true) } },
    onError   = { e -> updateState { it.copy(error = e) } }
) { details -> updateState { it.copy(pokemon = details) } }

The compiler infers O = PokemonDetails from the reified type parameter. Inside onDone, result is PokemonDetails? — statically typed. No cast at the call site.

The type recovery happens inside ResultState.parse<O>:

inline fun <reified O> parse(
    onRunning: (String?) -> Unit = {},
    onError: (Throwable?) -> Unit = {},
    onComplete: (O?) -> Unit = {},
) {
    when (this) {
        is Running -> onRunning(this.message)
        is Error   -> onError(this.error)
        is Complete<*> -> this.data?.let {
            it.takeIf { it is O }
                ?.let { result -> onComplete(result as O?) }
                ?: run { onError(IllegalArgumentException(
                    "Expected output of type ${O::class.simpleName}; got ${data?.let { data::class.simpleName }}"
                )) }
        } ?: run { onComplete(null) }
    }
}

The Complete<*> star projection in the when branch is not stylistic — it's required by the JVM's type erasure. Writing is Complete<O> is illegal at runtime because the generic parameter is erased; the JVM only sees Complete, not Complete<PokemonDetails>. The star projection is an honest acknowledgment of that: "I know this is a Complete, but I can't assert what it contains yet." The payload type is recovered one step later, inside the branch, where takeIf { it is O } uses the reified type token to perform the actual check. This two-step dance — structural match via star projection, then type recovery via reification — is the idiomatic Kotlin solution to the erasure problem at sealed class boundaries.

If the data is the expected type, the cast is safe, and onComplete receives a typed value. If not, the mismatch is routed to onError as an IllegalArgumentException with a diagnostic message naming both the expected and actual type.

A Single Entry Point as a Standard

Before examining the type mechanics in detail, it's worth stepping back and recognizing what collectUseCase is doing at the team level: it is the only sanctioned way to consume a use case in this codebase.

That's not a coincidence, and it's not just ergonomics. Every developer writing a new ViewModel hits the same function, receives the same structure, and is guided towards the same three concerns: what happens while loading, what happens on failure, and what happens on success. There is no alternative path — no way to collect { state -> ... } raw ResultState directly in a ViewModel without bypassing the base class entirely or going through the ceremony of exposing the use case state for collection within a viewModelScope.launch block. This meta-contract is strictly a team-level decision, and is by no means religiously enforced. Rather, it is the teams' agreed-upon convention aimed at readability, convenience, and standardization across potential verticals.

This matters for code review and maintenance in a way that documentation never can. You can write a coding standard that says "always handle the running and error states." You can also write collectUseCase, which makes not handling them an active decision that requires extra effort. The default onError implementation is:

crossinline onError: (Throwable?) -> Unit = { e -> onUseCaseError(e) }

onUseCaseError logs the throwable. A developer who forgets to pass an onError handler doesn't silently swallow failures — the fallback ensures breakage is still observed, just in logcat rather than the UI. Omitting error handling is now a deliberate downgrade, not an oversight.

The explicit type annotation at the call site — collectUseCase<PokemonDetails> — is also load-bearing as communication. It's documentation that can't become stale: whoever reads this call knows exactly what the ViewModel expects this use case to produce, without navigating to the use case's definition. It turns a consumption pattern into a declaration of intent.

What "Reified as a Bridge" Means in Practice

Reified type parameters exist specifically to recover type information that is erased at runtime. Kotlin erases generic types — a List<String> and a List<Int> are the same List at runtime. Reification retains the type token, making O::class and is O valid at runtime in inline functions.

The pattern here uses reification to bridge two type worlds:

Compile-time world: UseCase<PokemonDetails> — the use case is typed to its output.
Runtime world: StateFlow<ResultState?> — type information is erased at the shared channel level.
Recovery point: parse<O>() — reification reconstructs the type token at the collection site.

This bridge appears at the UI/domain boundary because that's where the erasure is intentional. The ResultState channel should be untyped at the ViewModel level — you want to collect multiple use cases with different output types through a single mechanism. Reification lets you express "I expect this to be of type O" at the point where you actually consume the value, without forcing every use case through a differently-typed channel.

The Path of Breakage

This is where the pattern earns most of its justification, and it's worth being precise about.

Consider what happens without parse<O>(). The raw alternative at the ViewModel collection site would look something like:

useCase.state.collect { state ->
    when (state) {
        is ResultState.Complete<*> -> {
            val data = state.data as? PokemonDetails  // as? cast
            if (data != null) updateState { it.copy(pokemon = data) }
        }
        // ...
    }
}

The as? cast is the failure mode. If state.data is actually a PokemonDto — because a mapping step was accidentally skipped somewhere in the call chain — the cast returns null silently. The UI receives a copy(pokemon = null). Nothing renders. There is no error. No log. No stack trace. A developer debugging this sees a blank screen and starts at square one.

The parse<O>() approach routes that same mismatch differently:

it.takeIf { it is O }
    ?.let { result -> onComplete(result as O?) }
    ?: run { onError(IllegalArgumentException(
        "Expected output of type ${O::class.simpleName}; got ${data?.let { data::class.simpleName }}"
    )) }

The same scenario — PokemonDto where PokemonDetails was expected — now produces an IllegalArgumentException with the message: "Expected output of type PokemonDetails; got PokemonDto." That exception is passed to onError, which routes it to the ViewModel's error state, which renders an error in the UI.

The difference in diagnosability is significant. In QA or during local testing, a visible error with a type name in the message points immediately to the mapping layer. The developer knows which use case is involved (they called getPokemon.collectUseCase<PokemonDetails>), what was expected (PokemonDetails), and what was actually received (PokemonDto). The breakage surface is named, localized, and actionable before the code ever reaches a release branch.

This is the pattern's core value proposition: type mismatches that would silently corrupt state instead generate observable, diagnosable failures during development. The system doesn't prevent the upstream bug — a wrong mapping is still a wrong mapping — but it ensures the downstream symptom is never a mystery. There's a clear and consistent path from breakage to identification.

It also means the pattern scales with the codebase. As more use cases are added, each one follows the same contract. A refactor that changes GetPokemon to return PokemonSummary instead of PokemonDetails doesn't silently break the ViewModel — it loudly breaks at runtime the first time the use case is collected, with a message that names exactly what changed. The type annotation at the call site becomes a lightweight contract test.

The Residual Cost

Naming these benefits doesn't erase the genuine trade-offs.

The type check remains runtime, not compile-time. The compiler cannot catch a mismatch between UseCase<PokemonDto> emitting into collectUseCase<PokemonDetails>. The type guard catches it, but during testing, not during compilation. If your test coverage of the happy-path data flow is thin, the mismatch can reach a release build.

The inline declaration has a direct impact on unit testing. Because collectUseCase is inline, MockK and Mockito cannot mock or spy on it at the function level — you can't assert "was collectUseCase called with the right type." In practice, this turns out to be a non-issue, and arguably a nudge in the right direction: you test the ViewModel by emitting ResultState values from a fake UseCase.state flow and asserting on the resulting ViewModel.state. Since state is a plain StateFlow<ResultState?>, wiring a test double is straightforward — every { useCase.state } returns MutableStateFlow(ResultState.Complete(pokemonDetails)) — and testing the output rather than the wiring is a more meaningful assertion anyway. The one place this becomes relevant is verifying error routing: emitting a ResultState.Complete containing the wrong type (e.g., PokemonDto instead of PokemonDetails) in a test will confirm that onError is invoked with the IllegalArgumentException, giving you a concrete test for the contract the pattern promises.

Inline functions with crossinline lambdas have constraints. The crossinline onDone parameter cannot use non-local returns or call suspend functions directly without explicit suspend on the lambda type. The signature accounts for this — onDone: suspend (O?) -> Unit — but it's a constraint the caller must be aware of.

Three simultaneous generic contexts add cognitive load. A HomeViewModel calling getPokemon.collectUseCase<PokemonDetails> is in BaseViewModel<HomeState> (class generic), calling an extension on UseCase<PokemonDetails> (receiver generic), with its own reified O = PokemonDetails (function generic). That's a lot to hold at once for someone unfamiliar with the pattern.

These costs are real. They're also bounded: the cognitive overhead is paid once when learning the pattern, the compile-time limitation is mitigated by the runtime guard, and the crossinline constraints are surfaced immediately by the compiler when you try to violate them.

When This Pattern Earns Its Complexity

The pattern is justified when all three of the following are true:

You have a shared communication channel that must erase type information (a StateFlow<SealedBase?>).
Consumers need typed access to the payload on the other side (arguably the most important constraint).
Silent type failures are unacceptable — mismatches should be observable and diagnosable (Also, just good practice).

If your use cases emit a different sealed class per output type, you don't need this — the types are preserved all the way to the consumer. If as?-with-null is an acceptable failure mode, you don't need the runtime guard. If the team is small enough that shared conventions can be maintained by proximity, the enforced entry point is just overhead.

But if you're building a ViewModel layer that will be extended by multiple developers across a growing feature set — where the distance between "use case author" and "ViewModel author" creates risk — the combination of a single enforced collection mechanism + explicit type declaration + diagnostic failure routing is a structural answer to a coordination problem. It turns what could be a verbal convention ("always annotate the expected type," "always handle errors") into something the codebase enforces on its own.

Type safety through a type-erased channel isn't a contradiction. It's a deliberate choice about where to bear the cost of erasure, made in favor of visibility over silence.

Lean Caching - A Custom NetworkBoundResource in Kotlin

Tom Horvat — Thu, 26 Mar 2026 16:57:33 +0000

Orchestrating data between a remote API and a local database is a foundational problem in mobile development. While the industry consensus rightly leans toward the Single Source of Truth pattern, the implementation often degrades into massive, fragile repository classes littered with boilerplate try-catch blocks and manual thread switching.

Solving this does not require a heavy, third-party state-management library. A clean, generic networkBoundResource built with Kotlin Flows and Coroutines is highly effective, provided you leverage Kotlin's advanced language features correctly.

Let me explain by demonstrating this pattern in my RandomPokemon project. By focusing on reified generics, inline functions, and structured concurrency, I’ve created a highly fault-tolerant data layer that I drop into my projects to handle caching without the bloat.

State Representation: Rethinking ResultState

Orchestrating complex data flows requires a strict contract for state representation. A standard sealed class handles the basic loading, success, and error states, but the mechanism used to unwrap that state dictates the cleanliness of the presentation layer. The versatility of the ResultState lends itself well to be used in API call returns, I/O operations, or for use cases being observed by the ViewModel.

sealed class ResultState {
    data class Complete<out O>(val data: O?) : ResultState()
    data class Running(val message: String? = null) : ResultState()
    data class Error(val error: Throwable? = null) : ResultState()

    inline fun <reified O> parse(
        onRunning: (String?) -> Unit = {},
        onError: (Throwable?) -> Unit = {},
        onComplete: (O?) -> Unit = {},
    ) {
        when (this) {
            is Running -> onRunning(this.message)
            is Error -> onError(this.error)
            is Complete<*> -> this.data?.let {
                it.takeIf { it is O }?.let { result -> onComplete(result as O?) }
                    ?: run { onError(IllegalArgumentException("Expected output of type ${O::class.simpleName}; got ${data?.let { data::class.simpleName }}")) }
            } ?: run { onComplete(null) }
        }
    }
}

Standard state implementations often force the caller to write repetitive when statements and perform unsafe casts in the UI or ViewModel. I intentionally avoid this by relying on the inline fun parse function to safely handle type checking and casting at runtime. If the type does not match, it gracefully routes to the onError block, preventing an abrupt ClassCastException and keeping the app's crash-free rate intact.

The Orchestrator: networkBoundResource

My core orchestrator is a single, highly optimized function. Relying heavily on inline and crossinline, it eliminates the runtime overhead associated with the higher-order functions passed into it.

inline fun <reified DomainType, reified DtoType> networkBoundResource(
    crossinline query: () -> Flow<ResultState>,
    crossinline fetch: suspend () -> ResultState,
    crossinline saveFetchResult: suspend (DtoType) -> Unit,
    crossinline shouldFetch: (DomainType?) -> Boolean = { it == null },
    crossinline mapDtoToDomain: (DtoType) -> DomainType,
    crossinline onCachePresent: () -> Unit = {}
) = flow {
    emit(ResultState.Running("Checking cache..."))
    val cachedDataResult = query().last()

    var cachedData: DomainType? = null
    cachedDataResult.parse<DomainType>(
        onError = { Timber.w(it, "Cache returned an error.") }
    ) { cachedData = it }

    if (shouldFetch(cachedData)) {
        emit(ResultState.Running("Cache miss. Fetching from remote..."))

        when (val remoteResult = fetch()) {
            is ResultState.Complete<*> -> {
                val dto = remoteResult.data as? DtoType

                if (dto != null) {
                    emit(ResultState.Complete(mapDtoToDomain(dto)))

                    supervisorScope {
                        launch {
                            try {
                                saveFetchResult(dto)
                            } catch (e: Exception) {
                                Timber.e(e, "Failed to save network resource to cache.")
                            }
                        }
                    }
                } else {
                    emit(ResultState.Error(IllegalStateException("Type mismatch: Remote fetch did not return the expected DTO.")))
                }
            }
            is ResultState.Error -> emit(remoteResult)
            is ResultState.Running -> emit(remoteResult)
        }
    } else {
        onCachePresent()
        emit(ResultState.Complete(cachedData!!))
    }
}

Two specific architectural decisions drive this implementation, focusing on performance and fault tolerance:

Immediate UI Emissions: When the remote fetch succeeds, the code emits the Complete state before initiating the database save. Disk I/O is slow. Forcing the UI to wait for Room to finish inserting records is an unnecessary bottleneck. The user gets the mapped domain model instantly.
Detached Caching: Launching saveFetchResult inside a supervisorScope acts as a defensive shield. If the database insertion fails due to a constraint violation or disk issue, the exception is caught and logged by Timber. The overarching coroutine running the Flow does not crash, and the UI retains the successfully fetched in-memory data.

Implementation: Concurrent Caching

An abstraction is only as effective as its call site. Integrating this into my PokemonRepoImpl demonstrates how I handle complex, relational data saving without blocking the thread.

class PokemonRepoImpl(
    private val remote: PokemonRepo.Remote,
    private val local: PokemonRepo.Local,
    private val dispatchers: DispatcherProvider
) : PokemonRepo {
    override fun getPokemonById(id: Long) = networkBoundResource<PokemonDetails, PokemonDto>(
        query = { local.getPokemonById(id) },
        fetch = { remote.getPokemonById(id).last() },
        saveFetchResult = { dto -> cacheRemotePokemon(dto.toDomainModel()) },
        mapDtoToDomain = { dto -> dto.toDomainModel() }
    )

    private suspend fun cacheRemotePokemon(details: PokemonDetails) {
        supervisorScope {
            val saveOperations: List<Pair<String, suspend () -> Unit>> = listOf(
                "pokemon" to { local.savePokemon(details.pokemon) },
                "cries" to { local.saveCries(details.cries) },
                "sprites" to { local.saveSprites(details.sprites) },
                "abilities" to { local.saveAbilities(details.abilities) }
            )

            saveOperations.forEach { (name, action) ->
                launch(dispatchers.io) {
                    try {
                        action()
                    } catch (e: Exception) {
                        Timber.e(e, "Error caching $name")
                    }
                }
            }
        }
    }
}

Mapping a large API payload to a relational database requires splitting the data into multiple tables. Executing these inserts sequentially scales poorly.

By wrapping the inserts in a supervisorScope and iterating through a list of saveOperations with launch(dispatchers.io), this repository performs concurrent database inserts. More importantly, the supervisorScope ensures fault isolation. If the API returns a malformed URL for a sprite that violates a database constraint, that specific coroutine fails and logs an error, but the parent scope remains active, allowing the pokemon, cries, and abilities to be cached successfully.

Final Thoughts

This implementation is my take on a pragmatic approach to Android architecture. Combining reified generics for type safety, inline functions for zero-overhead abstractions, and structured concurrency for fault-tolerant caching - yields a repository layer that is highly readable and extremely resilient. It solves a universal problem by leaning on the language, entirely avoiding the need for bloated external dependencies.

Stop Copying Gradle Code

Tom Horvat — Wed, 25 Mar 2026 20:32:55 +0000

If you've worked on a multi-module Android project, you know the pain: build.gradle.kts files multiplying like rabbits, each containing the exact same Android compileSdk, Kotlin compiler options, and Compose configurations. When you need to bump a version or change a compiler flag, you end up doing a massive "Find and Replace" across 20 different modules.

We know we shouldn't copy and paste application code, yet we routinely accept copy-pasting our build configuration.

It's time to stop. In this article, we'll explore how to use a build-logic module to create custom Gradle convention plugins. By moving boilerplate out of your module-level build files, you can enforce consistency across your entire project and make maintaining your build system a breeze.

To demonstrate, we will reference a real-world implementation from the RandomPokemon repository.

The "After" Picture: A Clean `app/build.gradle.kts`

Before we look at how to build convention plugins, let's look at why we want them.

Here is what the final app/build.gradle.kts looks like after migrating to convention plugins:

plugins {
    // Plugins
    id("myapp.android.application")
    id("myapp.android.compose")
}

dependencies {
    // Modules
    implementation(project(":core"))
    implementation(project(":common"))
    implementation(project(":navigation"))
    implementation(project(":landing"))
    // Module specific dependencies
    implementation(libs.koin)
    implementation(libs.voyager.navigator)
    implementation(libs.timber)
}

NOTE: Starting with Gradle 9, significant changes have been introduced in the way how application and library modules get configured

Notice what’s missing: No compileSdk, no minSdk, no buildFeatures { compose = true }, no Kotlin compiler arguments, and no core Compose dependencies. All of that complex boilerplate is completely hidden behind our custom plugins. The app-level build file is now strictly concerned with things specific to the app module.

Setting Up the `build-logic` Module

To achieve this, we create a completely separate, standalone Gradle build inside our main project directory called build-logic. As with any new module you want to add to your project, for Gradle to know it exists, you must add it to the project level settings.gradle.kts. The only difference is, since this is a build folder, the keyword is different:

// Pre Gradle 9

includeBuild("build-logic") // <-- add this before all other inclusions
include(":app")
...

// Gradle 9
pluginManagement {
    repositories {
        google {
            content {
                includeGroupByRegex("com\\.android.*")
                includeGroupByRegex("com\\.google.*")
                includeGroupByRegex("androidx.*")
            }
        }
        mavenCentral()
        gradlePluginPortal()
    }
    includeBuild("build-logic") // <-- the includeBuild instruction gets moved to the pluginManagement block
}

Because it's an isolated build, Gradle doesn't automatically know about our primary project's version catalog (libs.versions.toml). We need to explicitly link it. Also, add entries into the catalog so that the Gradle script can reach them:

// Pre Gradle 9
[versions]
agp = "8.13.2"
kotlin = "2.3.20"
room = "2.8.4"
...
[libraries]
android-gradle = { group = "com.android.tools.build", name = "gradle", version.ref = "agp" }
kotlin-gradle = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
room-gradle = { group = "androidx.room", name = "room-gradle-plugin", version.ref = "room" }
...

// Gradle 9 introduces builtIn Kotlin so we need to remove it from the plugins block

[versions]
# Gradle & Kotlin
agp = "9.1.0"
kotlin = "2.3.20"
ksp = "2.3.6"

# Data
room = "2.8.4"
...

[libraries]
# Gradle & Kotlin Plugins
android-gradle = { group = "com.android.tools.build", name = "gradle", version.ref = "agp" }
kotlin-gradle = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
room-gradle = { group = "androidx.room", name = "room-gradle-plugin", version.ref = "room" }
...

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
room = { id = "androidx.room", version.ref = "room" }
// the kotlin-android plugin has been removed
// kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

NOTE: gradle.properties will also be edited when you migrate from Gradle 8 to 9, feel free to clean up everything you do not need or use. I am still dependent on the newDsl = false flag since the official protobuf plugin that I am using is not compatible with Gradle 9 features

Gradle 9 only

The kotlin.android plugin needs to be removed from your project level gradle.build.kt .

1. Linking the Version Catalog (`build-logic/settings.gradle.kts`)

Create a settings.gradle.kts file inside your new build-logic directory. We need to tell this separate build where to find our shared versions and dependencies:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    versionCatalogs {
        create("libs") {
            from(files("../gradle/libs.versions.toml")) // <-- This points to your version catalog
        }
    }
}

2. Configuring Dependencies (`build-logic/build.gradle.kts`)

Next, inside build-logic/build.gradle.kts, we define the dependencies that our plugins will need to compile. We use compileOnly so we don't force our plugin's AGP/Kotlin versions onto the project that consumes this plugin.

This is also where we register our plugins so Gradle knows what ID maps to which class:

plugins {
    `kotlin-dsl`
}

dependencies {
    compileOnly(libs.android.gradle)
    compileOnly(libs.kotlin.gradle)
    compileOnly(libs.room.gradle)
}

gradlePlugin {
    plugins {
        register("myapp.android.library") {
            id = "myapp.android.library"
            implementationClass = "AndroidLibraryConventionPlugin"
        }

        register("myapp.android.application") {
            id = "myapp.android.application"
            implementationClass = "AndroidApplicationConventionPlugin"
        }

        register("myapp.android.compose") {
            id = "myapp.android.compose"
            implementationClass = "AndroidComposeConventionPlugin"
        }
    }
}

Creating the Plugins

Now for the fun part: writing the actual plugins. In build-logic/src/main/kotlin/, we write standard Kotlin classes that implement Gradle's Plugin<Project> interface.

A Focused, Reusable Plugin: `ProjectPluginExtensions.kt`

First, let's look at how to centralize base Android and Kotlin configuration. The best practice here is to write an extension function that configures the CommonExtension (which both Android Libraries and Android Applications use), and then call that function from a concrete Plugin class.

Here is the setup and the usage example of how it gets applied:

// Pre Gradle 9
internal fun Project.configureKotlinAndroid(
    commonExtension: CommonExtension<*, *, *, *, *, *>,
) {
    commonExtension.apply {
        compileSdk = 36
        defaultConfig {
            minSdk = 31
        }

        compileOptions {
            sourceCompatibility = JavaVersion.VERSION_21
            targetCompatibility = JavaVersion.VERSION_21
        }
    }

    tasks.withType<KotlinCompile>().configureEach {
        compilerOptions {
            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
        }
    }
}

// Gradle 9:
internal fun Project.configureKotlinAndroid(
    commonExtension: CommonExtension, // <-- CommonExtension does not accept type parameters
) {
    commonExtension.apply {
        compileSdk = 36

        defaultConfig.apply { // <-- change in method of accessing the minSdk property
            minSdk = 31
        }

        compileOptions.apply { // <-- change in method of accessing the compileOptions property
            sourceCompatibility = JavaVersion.VERSION_21
            targetCompatibility = JavaVersion.VERSION_21
        }
    }

    tasks.withType<KotlinCompile>().configureEach {
        compilerOptions {
            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
        }
    }
}

// Pre Gradle 9
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.library")
            pluginManager.apply("org.jetbrains.kotlin.android")

            extensions.configure<LibraryExtension> {
                configureKotlinAndroid(this) // <-- Use the extension function with the LibraryExtension

                // Set library specific flags, general build type configuration, etc.
            }
        }
    }
}

// Gradle 9
import com.android.build.api.dsl.LibraryExtension // <-- New import for LibraryExtension

class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.library")
            // pluginManager.apply("org.jetbrains.kotlin.android") <-- this in not needed anymore

            extensions.configure<LibraryExtension> {
                configureKotlinAndroid(this) // <-- Use the extension function with the LibraryExtension

                // Set library specific flags, general build type configuration, etc.
            }
        }
    }
}

By splitting the logic, an AndroidLibraryConventionPlugin can easily call configureKotlinAndroid(this) on its LibraryExtension, guaranteeing identical setups across your entire project. The same logic applies to a BaseAppModuleExtension:

// Pre Gradle 9
class AndroidApplicationConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.application")
            pluginManager.apply("org.jetbrains.kotlin.android")

            extensions.configure<BaseAppModuleExtension> {
                configureKotlinAndroid(this) // <-- Use the extension function with the BaseAppModuleExtension

                // Set app module specific flags
                namespace = "com.example.myapp"

                defaultConfig {
                    applicationId = "com.example.myapp"
                    targetSdk = 36
                    versionCode = 1
                    versionName = "1.0.0"
                }
            }
        }
    }
}

// Gradle 9
import com.android.build.api.dsl.ApplicationExtension

class AndroidApplicationConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("com.android.application")
            // pluginManager.apply("org.jetbrains.kotlin.android") <-- this in not needed anymore 

            extensions.configure<ApplicationExtension> { // <-- Different extension class
                configureKotlinAndroid(this) // <-- Use the extension function with the BaseAppModuleExtension

                // Set app module specific flags
                namespace = "com.example.myapp"

                defaultConfig {
                    applicationId = "com.example.myapp"
                    targetSdk = 36
                    versionCode = 1
                    versionName = "1.0.0"
                }
            }
        }
    }
}

A Complex Plugin: `AndroidComposeConventionPlugin.kt`

Sometimes a plugin needs to do more than just set flags—it needs to pull in dependencies and configure specific tooling features. Compose is a perfect candidate for this.

Here is an example of a plugin that configures Compose and injects required dependencies directly into the module applying it:

class RandomPokemonAndroidComposeConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            val libs = extensions.getByType<VersionCatalogsExtension>().named("libs")

            pluginManager.apply("org.jetbrains.kotlin.plugin.compose")

            pluginManager.withPlugin("com.android.application") {
                extensions.configure<ApplicationExtension> {
                    buildFeatures.compose = true
                }
            }
            pluginManager.withPlugin("com.android.library") {
                extensions.configure<LibraryExtension> {
                    buildFeatures.compose = true
                }
            }

            dependencies {
                "implementation"(platform(libs.findLibrary("androidx.compose.bom").get()))
                "implementation"(libs.findLibrary("androidx.ui").get())
                "implementation"(libs.findLibrary("androidx.ui.tooling.preview").get())
                "implementation"(libs.findLibrary("androidx.material3").get())
            }
        }
    }
}

By applying this single plugin, any module in your project that implements this plugin immediately gets Compose enabled, the correct Compose compiler linked, the BOM applied, and the tooling dependencies configured. If you ever need to update the Compose BOM or compiler, you do it centrally in your version catalog. Your feature module is clean and only lists specific flags and dependencies particular to it.

 plugins {
    id("myapp.android.library")
    id("myapp.android.compose")
}

android {
    namespace = "io.bitbot.bemusedbaboon.landing"
}

dependencies {

    implementation(project(":core"))
    implementation(project(":common"))
    implementation(project(":navigation"))

    implementation(libs.timber)

    implementation(libs.koin)
    implementation(libs.koin.compose)

    implementation(libs.voyager.navigator)

    implementation(libs.coil.compose)
    implementation(libs.coil.network)
}

Bonus: Dynamically Generating Library Namespaces

If you want to take your boilerplate reduction a step further, look at how you declare namespaces in your library modules.

Typically, every library's build.gradle.kts requires an android block just to declare a deeply nested namespace:

android { 
    namespace = "com.example.myapp.commons" 
}

Since the base namespace com.example.myapp never changes, repeating it across dozens of modules is prone to typos and adds unnecessary noise. Because our build-logic is written in Kotlin, we can create a simple top-level extension function to handle this for us.

1. The Helper Function (`build-logic/src/man/kotlin/ProjectPluginExtensions.kt` )

Create a new Kotlin file in your convention plugin source directory. We'll define our base namespace as a constant and write an extension function on Project that configures the LibraryExtension:

// Define your single source of truth for the base namespace
private const val BASE_NAMESPACE = "com.example.myapp"

/**
 * Automatically applies the base namespace and appends the provided suffix.
 */
fun Project.libraryNamespace(suffix: String) {
    extensions.configure<LibraryExtension> {
        namespace = "$BASE_NAMESPACE.$suffix"
    }
}

2. The Final Library `build.gradle.kts`

Now, you can completely eliminate the android { ... } block from your library modules. Whenever you create a new library, you simply call your custom function directly in the build script:

plugins {
    id("myapp.android.library")
    id("myapp.android.room")
}

libraryNamespace("commons")

dependencies {
    ...
}

By adding this tiny extension function, your library build scripts become incredibly concise, and your project enforces a strict, typo-free naming convention for all module namespaces.

Conclusion

Migrating your Gradle build configuration to custom convention plugins requires an initial upfront investment, but the ROI is massive:

Readability: Module-level build.gradle.kts files become declarative summaries of what a module is, rather than a script of how it compiles.
Safety: New modules are guaranteed to use the correct compiler flags, Java targets, and core dependencies.
Maintainability: Updating your project to a new Java version, bumping compileSdk, or changing compiler arguments happens in exactly one place.

Stop copying Gradle code. Treat your build configuration with the same architectural respect you give to your application architecture. Your future self—and your team—will thank you.