I was looking through one of my older multi-module projects this morning—a little utility app with a :core module, a :network module, and the :app module. I realized I needed to bump the version of Retrofit and OkHttp to patch a security vulnerability. I started by opening network/build.gradle.kts, changed the version, and then... I remembered the :core module also uses OkHttp for some low-level interceptors. Then I remembered the :app module has a specific test dependency on it.

It's a tedious game of "Find and Replace," and honestly, it's where bugs crawl in. If I miss one module, I end up with a classpath conflict that takes twenty minutes to debug. I'm tired of doing it the old way.

The redundant string problem

Here is what my dependency blocks looked like across those three files. It's a lot of duplication:

// In :network/build.gradle.kts
implementation("com.squareup.retrofit2:retrofit:2.9.0")
implementation("com.squareup.okhttp3:okhttp:4.11.0")

// In :core/build.gradle.kts
implementation("com.squareup.okhttp3:okhttp:4.11.0")

// In :app/build.gradle.kts
testImplementation("com.squareup.okhttp3:okhttp:4.11.0")

I used to handle this with a buildSrc folder or a bunch of ext properties in the root project. But buildSrc has a downside: any time you change a version number in there, Gradle thinks the entire build logic has changed and invalidates the build cache for the whole project. On a large project, that's a massive waste of time. I want a way to change a version number without triggering a full re-compile of my build scripts.

Trying out the TOML approach

I've been seeing "Version Catalogs" mentioned in the Gradle docs. The idea is to move these strings out of the Kotlin files and into a dedicated configuration file. Let's see if I can get this working.

First, I'll create a file at gradle/libs.versions.toml. I'm noticing that the format is split into sections. I'll start by defining the versions themselves, then the libraries that use those versions.

[versions]
retrofit = "2.9.0"
okhttp = "4.11.0"

[libraries]
retrofit-core = { group = "com.squareup.retrofit2", name = "retrofit", version.ref = "retrofit" }
okhttp-core = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }

I like that version.ref allows me to decouple the version number from the library definition. If I have three different Retrofit artifacts (like the core and the Moshi converter), they can all point to the same retrofit version variable.

Connecting the dots in Gradle

Now, if I just go back to my build.gradle.kts and try to use these, nothing happens. Gradle doesn't magically know about the TOML file unless it's in the default location (gradle/libs.versions.toml). Since I put it there, Gradle automatically generates a type-safe accessor called libs.

Let's try to swap out the hardcoded strings in :network/build.gradle.kts:

// Old way
// implementation("com.squareup.retrofit2:retrofit:2.9.0")

// New way
implementation(libs.retrofit.core)
implementation(libs.okhttp.core)

Wait, I noticed something. In the TOML file, I named the library retrofit-core (with a hyphen), but in the Kotlin file, I'm using libs.retrofit.core (with a dot). Gradle is automatically converting those hyphens to dots to make them look like valid Kotlin properties. That's a nice touch—it keeps the TOML feeling like a config file and the Kotlin feeling like code.

Grouping dependencies into bundles

As I'm doing this, I realize that whenever I add Retrofit, I almost always add OkHttp. It's a pattern. I wonder if I can group them so I don't have to write two lines every single time. I'll add a [bundles] section to my TOML:

[bundles]
networking = ["retrofit-core", "okhttp-core"]

Now, let's see what happens in the build script. I can replace both implementation lines with just one:

dependencies {
    implementation(libs.bundles.networking)
}

This is much cleaner. Now, if I want to upgrade to Retrofit 2.11.0, I change one single line in libs.versions.toml, and every module in my project is updated instantly. No "Find and Replace," no classpath mismatches, and no massive build cache invalidation.

📋 Practical Task

Exercise: Migrating the Ktor Stack to a Version Catalog

You are working on a project with three modules: :app, :data, and :domain. Currently, the :data and :app modules are using hardcoded strings for Ktor and Kotlinx Serialization. Your goal is to migrate these to a Version Catalog to prevent version mismatch.

Current State:

// :data/build.gradle.kts
implementation("io.ktor:ktor-client-core:2.3.5")
implementation("io.ktor:ktor-client-cio:2.3.5")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")

// :app/build.gradle.kts
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")

Your Task:

1. Create a gradle/libs.versions.toml file.
2. Define versions for ktor (2.3.5) and serialization (1.6.0).
3. Define library aliases for ktor-client-core, ktor-client-cio, and kotlinx-serialization-json.
4. Create a bundle named ktor-stack that includes both Ktor libraries.
5. Rewrite the dependencies blocks in :data/build.gradle.kts and :app/build.gradle.kts to use the new libs accessors and the bundle.