Migrating Hilt from KAPT to KSP in Android Projects

Hilt dependency injection simplifies Android development, but migrating from KAPT to KSP requires compatible dependencies and configuration due to version conflicts between Kotlin, KSP, and Jetpack Compose.

Problem Statement

The core challenge arises from incompatible versions between:

1. Kotlin and KSP
2. Kotlin and Jetpack Compose
3. Hilt and KSP

Using mismatched versions causes build errors and failed code generation, preventing Hilt from working with KSP. Developers see cryptic build errors without clear resolution paths.

Solution Setup

Follow these configuration steps based on your Kotlin version:

A. For Kotlin < 2.0.0 (Stable Approach)

Project-level build.gradle.kts:

plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.23" apply false
    id("com.google.dagger.hilt.android") version "2.51" apply false
    id("com.google.devtools.ksp") version "1.9.23-1.0.20" apply false
}

App-level build.gradle.kts:

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.dagger.hilt.android")
    id("com.google.devtools.ksp")
}

android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.11" // Matches Kotlin 1.9.23
    }
}

dependencies {
    val hiltVersion = "2.51"
    implementation("com.google.dagger:hilt-android:$hiltVersion")
    ksp("com.google.dagger:hilt-compiler:$hiltVersion")
}

B. For Kotlin ≥ 2.0.0

Project-level build.gradle.kts:

plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(libs.plugins.hilt.android) apply false
    alias(libs.plugins.google.devtools.ksp) apply false
}

App-level build.gradle.kts:

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose) // Required for Kotlin ≥ 2.0
    alias(libs.plugins.hilt.android)
    alias(libs.plugins.google.devtools.ksp)
}

dependencies {
    implementation(libs.dagger.hilt)
    ksp(libs.dagger.hilt.compiler)
}

libs.versions.toml:

[versions]
kotlin = "2.0.21"
kotlin-ksp = "2.0.21-1.0.28" # Match Kotlin version
hilt = "2.51.1"

[libraries]
dagger-hilt = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
dagger-hilt-compiler = { group = "com.google.dagger", name = "hilt-compiler", version.ref = "hilt" }

[plugins]
android-application = { id = "com.android.application", version = "8.2.2" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
hilt-android = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
google-devtools-ksp = { id = "com.google.devtools.ksp", version.ref = "kotlin-ksp" }

Key Configuration Requirements

1. Version Compatibility Check
   • Cross-reference KSP releases for Kotlin
   • Jetpack Compose compatibility table
   • Hilt ≥ 2.48 supports KSP (official guide)

AVOID THESE MISTAKES

• Mixing hilt-android-compiler and hilt-compiler dependencies (use only hilt-compiler)
• Applying kotlinCompilerExtensionVersion with Kotlin ≥ 2.0
• Mismatching Kotlin and KSP versions (e.g., Kotlin 1.9.x needs KSP formatted as 1.9.x-1.0.y)

Verification Steps

1. Clean project after changes: ./gradlew clean
2. Remove generated KSP files: Delete build/generated/ksp
3. Rebuild: ./gradlew :app:assembleDebug

TROUBLESHOOTING

If issues persist:

1. Verify Kotlin/KSP alignment: kotlinVersion + kspVersionSuffix
2. Check duplicate Hilt dependencies
3. Ensure only one KSP plugin is applied
4. Confirm Jetpack Compose compatibility with Kotlin version

Why KSP Over KAPT?

• Faster builds: Direct symbol processing without Java stubs
• Kotlin-native: Better Kotlin type resolution
• Declarative processing: Reduced configuration complexity

By matching toolchain versions and using the correct Hilt dependencies, you'll benefit from faster builds while maintaining reliable dependency injection with Hilt.

Official Resources

• Hilt KSP Guide
• KSP Releases
• Compose-Kotlin Compatibility