This skill guides the setup of Dagger-Hilt for Dependency Injection in an
Android project, specifically using Gradle Kotlin DSL (gradle.kts),
Version Catalogs (libs.versions.toml), and KSP (Kotlin Symbol
Processing).
Setting up Hilt in gradle.kts can be error-prone. Using KSP is the modern best
practice as it is faster than KAPT.
Prerequisites
- The project must be using Gradle Version Catalogs (
libs.versions.toml). - The project must be using Kotlin DSL (
.gradle.ktsfiles).
Step 1: Update libs.versions.toml
Add the Hilt and KSP versions, libraries, and plugins to your
gradle/libs.versions.toml file.
[versions]
# Note: These are example versions. Verify against project needs or use latest stable.
hilt = "2.51.1"
ksp = "2.0.0-1.0.21" # MUST match your Kotlin version! (e.g., 2.0.0 -> 2.0.0-1.0.21)
androidxHilt = "1.2.0"
[libraries]
hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
hilt-compiler = { group = "com.google.dagger", name = "hilt-compiler", version.ref = "hilt" }
hilt-navigation-compose = { group = "androidx.hilt", name = "hilt-navigation-compose", version.ref = "androidxHilt" }
[plugins]
hilt-android = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
Step 2: Update Project-level build.gradle.kts
Register the Hilt and KSP plugins in the root build.gradle.kts file.
// Root build.gradle.kts
plugins {
// Note that the Android plugin MUST come first
// ...
// Then hilt
alias(libs.plugins.hilt.android) apply false
// Then other plugins (e.g. KSP).
alias(libs.plugins.ksp) apply false
}
Step 3: Update App-level build.gradle.kts
Apply the plugins and add the dependencies in your app module's
build.gradle.kts (usually app/build.gradle.kts).
// app/build.gradle.kts
plugins {
alias(libs.plugins.android.application)
alias(libs.plugins.hilt.android)
alias(libs.plugins.ksp)
}
dependencies {
implementation(libs.hilt.android)
implementation(libs.hilt.navigation.compose) // Essential for hiltViewModel() in Compose
ksp(libs.hilt.compiler)
}
Step 3.5: Multi-module Setup (Optional)
If your project has multiple modules (e.g., feature, data, core), follow
these rules:
- Root: Ensure plugins are declared with
apply falsein the rootbuild.gradle.kts(Step 2). - Feature/Library Modules: In each module that uses Hilt annotations (like
@Injector@Provides):- Apply the KSP plugin:
alias(libs.plugins.ksp) - If it's an Android module, apply Hilt:
alias(libs.plugins.hilt.android) - Add the compiler:
ksp(libs.hilt.compiler)
- Apply the KSP plugin:
- Avoid Duplicate Applications: Only the main app module should have the
@HiltAndroidAppclass.
Step 4: Perform Gradle Sync
After modifying the build files, you MUST perform a Gradle sync to enable Hilt dependencies.
Step 5: Create Application Class
Hilt requires a custom Application class annotated with @HiltAndroidApp.
package com.example.myapp
import android.app.Application
import dagger.hilt.android.HiltAndroidApp
@HiltAndroidApp
class MyApp : Application()
Step 6: Update AndroidManifest.xml
Register your custom Application class in the AndroidManifest.xml.
<application
android:name=".MyApp"
...>
</application>
Step 7: Annotate Hosting Activity
Any Activity that hosts Hilt-injected Composables or Fragments must be annotated
with @AndroidEntryPoint.
import dagger.hilt.android.AndroidEntryPoint
import androidx.activity.ComponentActivity
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
// ...
}
Step 8: Basic Usage (iOS Analogy)
After setup, use these annotations to inject dependencies. In iOS, you might have used Resolver or Swinject; in Android, Hilt automates this.
ViewModel Injection
import androidx.lifecycle.ViewModel
import dagger.hilt.android.lifecycle.HiltViewModel
import javax.inject.Inject
@HiltViewModel
class MyViewModel @Inject constructor(
private val repository: MyRepository
) : ViewModel()
Usage in Compose
import androidx.compose.runtime.Composable
import androidx.hilt.navigation.compose.hiltViewModel
@Composable
fun MyScreen(viewModel: MyViewModel = hiltViewModel()) {
// ...
}
Antipatterns
DO
- DO use
alias(libs.plugins.hilt.android)andalias(libs.plugins.ksp)inbuild.gradle.kts. - DO use
kspforhilt-compilerdependency. - DO ensure KSP version matches your Kotlin version exactly.
- DO remove the
kotlin-kaptplugin if it is no longer needed to avoid build overhead. - DO check Knowledge Base for project-specific patterns.
DON'T
- DON'T use KAPT if you can use KSP.
- DON'T hardcode versions in
build.gradle.kts. - DON'T forget to add
@AndroidEntryPointto your Activity if it hosts Hilt-injected Composables.