KotlinプロジェクトでDagger HiltにKSPを使用

TIP

KAPTからKSPへの移行で発生するほとんどのエラーは、Kotlin・KSP・Composeコンパイラのバージョン不整合が原因です。互換性さえ確保すれば設定はシンプルです。

主な問題と解決の要点

問題点	解決策
バージョン互換性の欠如	Kotlin・KSP・Composeコンパイラの対応バージョンを厳守
古いKAPT設定の残留	gradle.propertiesでkapt.use.worker.api=trueを削除
冗長な依存関係	Hiltコンパイラ依存はhilt-compilerのみでOK

基本設定手順（Kotlin ≤ 1.9）

1. プロジェクトレベルの設定(build.gradle.kts)

// build.gradle.kts (Project Level)
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 // KSPバージョンはKotlinに連動
}

WARNING

KSPバージョン形式 X.Y.Z-A.B.C の最初の部分(X.Y.Z)は必ずKotlinバージョンと一致させる必要があります。 例: Kotlin 1.9.23 → KSP 1.9.23-1.0.20

2. アプリモジュールの設定(app/build.gradle.kts)

// app/build.gradle.kts (Module Level)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.dagger.hilt.android")
    id("com.google.devtools.ksp")
}

dependencies {
    // Hilt本体
    implementation("com.google.dagger:hilt-android:2.51")
    
    // KSP用コンパイラ (kaptではなくkspを使用)
    ksp("com.google.dagger:hilt-compiler:2.51")
    
    // Compose使用時のみ必要
    // implementation("androidx.hilt:hilt-navigation-compose:1.2.0")
}

3. Compose用設定（使用する場合）

android {
    buildFeatures {
        compose = true
    }
    composeOptions {
        // Kotlin 1.9.23の場合の互換バージョン
        kotlinCompilerExtensionVersion = "1.5.11"
    }
}

Version Catalogを使った管理例(libs.versions.toml)

プロジェクトがVersion Catalogを使用している場合:

[versions]
kotlin = "1.9.23"
ksp = "1.9.23-1.0.20"  # Kotlinバージョンと連動
hilt = "2.51"

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

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

設定ファイルから参照:

// build.gradle.kts (Module Level)
plugins {
    alias(libs.plugins.hilt.android)
    alias(libs.plugins.ksp.plugin)
}

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

Kotlin 2.0.0以降の変更点

DANGER

Kotlin 2.0.0からは追加でCompose compiler pluginが必要です。設定を省略するとビルドエラーが発生します。

1. libs.versions.tomlにプラグイン追加:

[versions]
kotlin = "2.0.21"
ksp = "2.0.21-1.0.28"  # Kotlin 2.0.21に対応

[plugins]
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

2. プロジェクトレベルでプラグイン宣言:

// settings.gradle.kts
pluginManagement {
    plugins {
        alias(libs.plugins.kotlin.compose)
        alias(libs.plugins.google.devtools.ksp)
    }
}

3. モジュールで適用:

plugins {
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.google.devtools.ksp)
    // ↓ kotlinCompilerExtensionVersionは不要に
}

よくあるエラーと解決策

1. クラスが見つからないエラー

   • 原因: Hiltの新旧バージョン混在
   • 解決: 全モジュールでhilt-androidとhilt-compilerを同一バージョンに統一

2. KSPがアノテーションを処理しない

   • ksp依存が正しく宣言されているか確認
   • kapt依存を完全に削除（build.gradleからkapt関連記述を除去）

3. Composeコンパイルエラー

   • 公式互換性マップでバージョン組み合わせを確認
   • Kotlin 2.0以降ではkotlinCompilerExtensionVersion設定を完全に削除

効果的なデバッグ方法

1. 依存関係ツリーを確認:

./gradlew :app:dependencies --configuration ksp

2. KSP出力を検査:

./gradlew clean
./gradlew --info  # エラー発生時のスタックトレースを詳細表示

TIP

Hilt公式はバージョン2.48以降で公式KSPサポートを開始しています。プロジェクトに合った最新安定版の使用を推奨します。