Gradle Configuration

Overview

Best practices for configuring Android Gradle builds: Version Catalogs as single source of truth, Kotlin DSL, dependency management, build performance, and common troubleshooting.

Version Catalog (libs.versions.toml)

Single source of truth for all dependency versions. Located at gradle/libs.versions.toml.

Structure

[versions]
kotlin = "2.1.21"
agp = "8.5.0"
compose-bom = "2024.12.01"
retrofit = "2.11.0"
mockk = "1.13.12"
coroutines = "1.8.1"

[libraries]
# Pattern: group-artifact = { module = "group:artifact", version.ref = "key" }
retrofit-core = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-converter-gson = { module = "com.squareup.retrofit2:converter-gson", version.ref = "retrofit" }

# BOM — no version here
compose-bom = { module = "androidx.compose:compose-bom", version.ref = "compose-bom" }
# BOM children — no version
compose-ui = { module = "androidx.compose.ui:ui" }
compose-material3 = { module = "androidx.compose.material3:material3" }

# Testing
mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
kotlinx-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "coroutines" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

[bundles]
# Group libraries used together
retrofit = ["retrofit-core", "retrofit-converter-gson"]
compose-core = ["compose-ui", "compose-material3"]

Usage in build.gradle.kts

// Type-safe accessors
dependencies {
    implementation(libs.retrofit.core)
    implementation(libs.retrofit.converter.gson)
    // or via bundle
    implementation(libs.bundles.retrofit)

    // BOM
    implementation(platform(libs.compose.bom))
    implementation(libs.compose.ui)
    implementation(libs.compose.material3)

    testImplementation(libs.mockk)
    testImplementation(libs.kotlinx.coroutines.test)
}

Module build.gradle.kts

Application Module

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    // your convention plugins
    id("my.android.application")
}

android {
    namespace = "com.example.myapp"
    // SDK versions come from convention plugin
}

dependencies {
    implementation(project(":feature:home"))
    implementation(project(":feature:profile"))
    implementation(libs.androidx.core.ktx)
}

Library Module

plugins {
    alias(libs.plugins.android.library)
    alias(libs.plugins.kotlin.android)
    id("my.android.library")    // convention plugin handles the rest
    id("my.android.unit.test")
}

android {
    namespace = "com.example.feature.home"
}

dependencies {
    implementation(project(":component:user"))
    implementation(libs.androidx.lifecycle.viewmodel)
}

Dependency Scopes

Prefer implementation over api. api leaks transitive dependencies, increases coupling, and slows compilation.

Dependency Conflict Resolution

Force a Version

// In root build.gradle.kts
configurations.all {
    resolutionStrategy {
        force(libs.kotlin.stdlib)
        // or for a specific module
        eachDependency {
            if (requested.group == "org.jetbrains.kotlin") {
                useVersion(libs.versions.kotlin.get())
                because("All Kotlin modules must use the same version")
            }
        }
    }
}

Exclude a Transitive Dependency

implementation(libs.someLibrary) {
    exclude(group = "com.google.guava", module = "guava")
}

View Dependency Tree

./gradlew :app:dependencies --configuration releaseRuntimeClasspath
# or specific module
./gradlew :feature:home:dependencies

Build Performance

gradle.properties

# Parallel execution
org.gradle.parallel=true

# Build cache
org.gradle.caching=true

# Configuration cache (Gradle 8+)
org.gradle.configuration-cache=true

# Increase heap for large projects
org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC

# AndroidX
android.useAndroidX=true

# R8 in debug (optional — faster debug builds)
android.enableR8.fullMode=false

Configuration Cache

# First run: configures + executes
./gradlew assembleDebug

# Subsequent runs: skips configuration phase
./gradlew assembleDebug  # ~50% faster

Incompatible tasks must be excluded:

org.gradle.configuration-cache.problems=warn

Compatibility Matrix (Critical)

Certain dependencies must align or builds fail:

Check before upgrading:

• AGP ↔ Gradle compatibility
• Kotlin ↔ Compose Compiler

Common Gradle Commands

# Build
./gradlew assembleDebug
./gradlew assembleRelease

# Test
./gradlew test                          # all unit tests
./gradlew :feature:home:test            # specific module

# Lint
./gradlew lint
./gradlew :feature:home:lint

# Clean
./gradlew clean

# Dependency insight
./gradlew dependencyInsight --dependency retrofit --configuration runtimeClasspath

# Check outdated dependencies
./gradlew dependencyUpdates              # requires com.github.ben-manes.versions plugin

# Build scan (requires agreement)
./gradlew build --scan

Kotlin DSL Tips

// Access version catalog in build script
val kotlinVersion = libs.versions.kotlin.get()

// Configure build type
android {
    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro",
            )
        }
        debug {
            applicationIdSuffix = ".debug"
            isDebuggable = true
        }
    }
}

// Product flavors
android {
    flavorDimensions += "environment"
    productFlavors {
        create("dev") {
            dimension = "environment"
            applicationIdSuffix = ".dev"
            buildConfigField("String", "BASE_URL", "\"https://dev.api.example.com\"")
        }
        create("prod") {
            dimension = "environment"
            buildConfigField("String", "BASE_URL", "\"https://api.example.com\"")
        }
    }
}

Checklist: Adding a Dependency

• Version declared in [versions] section of libs.versions.toml
• Library declared in [libraries] section with version.ref
• Added to module via libs.my.library (never hardcoded)
• Correct scope used (implementation vs testImplementation)
• Compatibility with existing versions verified
• No version conflicts introduced (run ./gradlew dependencies)

References

• Version Catalogs
• Android Gradle Plugin
• Gradle Build Performance
• Kotlin DSL for Gradle