Adding Hilt Dependencies Using libs.versions.toml in Android Studio

Problem: When adding Hilt dependencies to the libs.versions.toml file in a modern Android Studio project (using Kotlin DSL), you encounter unresolved reference errors in your build.gradle.kts files. The dependencies defined in the version catalog aren't recognized during sync, preventing successful project compilation.

This issue occurs because Hilt requires both plugin configuration and library dependencies to be properly declared across different configuration files. The solution requires coordinated updates to:

1. The libs.versions.toml version catalog
2. Project-level build configuration
3. App-level build configuration

---

Prerequisites

• Android Studio Iguana (2023.2.1+) or later
• AGP (Android Gradle Plugin) 8.0+
• Kotlin DSL build scripts (*.gradle.kts)
• Version Catalog enabled in your project

---

Solution: Configuring Hilt with KSP

Hilt now uses KSP (Kotlin Symbol Processing) instead of kapt for Kotlin projects. Follow these steps to configure Hilt dependencies:

1. Update libs.versions.toml

Add the following entries to your gradle/libs.versions.toml:

[versions]
hiltVersion = "2.51.1"  # Check latest version at: https://github.com/google/dagger/releases
kspVersion = "1.9.20-1.0.13"  # Match with your Kotlin version

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

[plugins]
hilt-android-plugin = { id = "com.google.dagger.hilt.android", version.ref = "hiltVersion" }
kotlin-ksp-plugin = { id = "com.google.devtools.ksp", version.ref = "kspVersion" }

Key notes:

• Use hiltVersion consistently for both libraries and plugins
• KSP version must be compatible with your Kotlin version

2. Configure Project-Level Build Script

Update your project's build.gradle.kts:

plugins {
    alias(libs.plugins.hilt.android.plugin) apply false
    alias(libs.plugins.kotlin.ksp.plugin) apply false
}

The apply false indicates these plugins should be available to subprojects but not applied globally.

3. Configure App-Level Build Script

Update your module's build.gradle.kts:

plugins {
    alias(libs.plugins.hilt.android.plugin)
    alias(libs.plugins.kotlin.ksp.plugin)
}

dependencies {
    // Hilt dependencies
    implementation(libs.hilt.android)
    ksp(libs.hilt.compiler)
    
    // Optional: Add these if using Hilt with other Jetpack components
    // implementation(libs.hilt.navigation.compose)
    // implementation(libs.hilt.work)
}

4. Sync and Clean Build

1. Click Sync Project with Gradle Files
2. Clean the project:

   ./gradlew clean

3. Rebuild:

   ./gradlew assembleDebug

---

💡 KSP vs kapt: Use KSP (`ksp` configuration) instead of `kapt` for Hilt in Kotlin projects. KSP processes Kotlin code faster and is the recommended approach for new projects.

<style> .tip-container { border-left: 3px solid #3b82f6; padding-left: 15px; margin: 20px 0; } .tip-title { font-weight: 600; color: #1d4ed8; margin-bottom: 5px; } </style>

---

Common Issues and Fixes

Sync Fails with "Plugin Requested but Not Applied"

Plugin [id: 'com.google.dagger.hilt.android'] was not found

Solution: Verify plugin aliases in your build.gradle.kts files exactly match the libs.versions.toml definitions. Watch for typos.

Unresolved References to libs

Unresolved reference: hilt

Solution:

1. Ensure all entries in libs.versions.toml are under [libraries] section
2. Use consistent naming patterns (e.g., dashes - vs underscores _)
3. Perform a File > Invalidate Caches / Restart

KSP Version Compatibility Issues

Kotlin version that was used to compile KSP is x.x.x expected version y.y.y

Solution: Make sure kspVersion in libs.versions.toml matches your project's Kotlin version. Check KSP Releases for compatible versions.

---

Alternative Using kapt (Legacy)

For projects still using Java annotation processing instead of KSP:

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

[plugins]
hilt-android-plugin = { id = "com.google.dagger.hilt.android", version.ref = "hiltVersion" }
kotlin-kapt-plugin = { id = "org.jetbrains.kotlin.kapt", version.ref = "kotlinVersion" }

plugins {
    id("kotlin-kapt")
    alias(libs.plugins.hilt.android.plugin)
}

dependencies {
    implementation(libs.hilt.android)
    kapt(libs.hilt.compiler)
}

⚠️ Deprecation Notice: kapt is superseded by KSP for Kotlin projects. Migrate to KSP for better performance.

---

Final Configuration Check

After syncing successfully, you should see the Hilt dependencies resolved in your project, enabling Hilt dependency injection throughout your Android application.