gradle-best-practices

Gradle Best Practices for Android (2025–2026)

Always use version catalog

• All dependency versions belong in gradle/libs.versions.toml — never hardcode versions in build.gradle.kts
• Reference with type-safe accessors: implementation(libs.androidx.core.ktx) not implementation("androidx.core:core-ktx:1.13.1")
• BOM imports: implementation(platform(libs.androidx.compose.bom))

Kotlin DSL (.kts) rules

• Use implementation(libs.xxx) — never Groovy syntax like implementation 'xxx:yyy:1.0'
• Type-safe accessors are preferred over string-based references
• buildFeatures { compose = true } required for Compose projects

Kotlin 2.0+ Compose setup (current standard)

// In plugins block of app/build.gradle.kts:
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)   // ← required for Kotlin 2.0+
}

# In libs.versions.toml plugins block:
[plugins]
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

Do NOT use kotlinOptions { kotlinCompilerExtensionVersion = "..." } — this is deprecated for Kotlin 2.0+.

SDK target versions

android {
    compileSdk = 36      // Android 16
    defaultConfig {
        minSdk = 24      // Android 7.0 — ~96% device coverage
        targetSdk = 36
    }
}

Play Store requirement: targetSdk must meet Google's current minimum target API level (check Play Console's target API requirements). Apps with outdated targetSdk receive policy warnings.

Java / Kotlin compile options

kotlinOptions is deprecated; set the JVM target with compilerOptions in a top-level kotlin {} block (outside android {}).

import org.jetbrains.kotlin.gradle.dsl.JvmTarget

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}
kotlin {
    compilerOptions {
        jvmTarget.set(JvmTarget.JVM_11)
    }
}

ProGuard for release builds (required)

buildTypes {
    release {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro"
        )
    }
}

Both isMinifyEnabled and isShrinkResources must be true for release. This reduces APK/AAB size significantly.

AGP ↔ Gradle wrapper compatibility

Check gradle/wrapper/gradle-wrapper.properties when updating AGP.

Signing config via local.properties (recommended)

import java.util.Properties

val localProps = Properties().apply {
    file("../local.properties").takeIf { it.exists() }?.inputStream()?.use { load(it) }
}

android {
    signingConfigs {
        create("release") {
            storeFile = file(localProps["KEYSTORE_PATH"] as String)
            storePassword = localProps["KEYSTORE_PASSWORD"] as String
            keyAlias = localProps["KEY_ALIAS"] as String
            keyPassword = localProps["KEY_PASSWORD"] as String
        }
    }
}

local.properties is excluded from git by Android Studio's default .gitignore — never commit it.

Build commands reference

./gradlew clean                 # Clean all build outputs
./gradlew bundleRelease         # Build release AAB (for Play Store)
./gradlew assembleRelease       # Build release APK (for direct install)
./gradlew signingReport         # Verify signing configuration
./gradlew dependencies          # Show full dependency tree