v1.0.0

Compare Source

Koin Compiler Plugin 1.0.0

The first stable release. RC1 shipped in April 2026; over the following weeks the safety pass, incremental-compilation handling, and K2.3.20 compatibility came together. The compiler-plugin path is now ready for production: full-graph compile-time safety, cross-module call-site validation, IC-aware safe-defaults, and K2.3.20 support.

Requires: Kotlin 2.3.20+ (K2) | Koin 4.2.1+

What's New Since 1.0.0-RC2

Compile-time safety expanded (A2/A3/A4)

• Circular dependency detection — cycles like A → B → A are caught during graph traversal in A2/A3, no longer waiting for runtime.
• Call-site validation with dynamic parameters — get<T> { parametersOf(...) } and ViewModel/inject sites with parametersOf {} flows are validated against the assembled graph.
• Compose-wrapped lambdas — A4 traverses Compose lambdas, so koinViewModel<T>() inside @Composable builders is validated like any other call site.
• Qualifier-collision guard — A4 reports when two definitions resolve to the same (raw class + qualifier) key, preventing silent last-wins overrides at runtime.
• KOIN-D007 — @Factory returning a type that extends a suspend fun interface is now blocked at compile time (previously crashed Fir2Ir).
• Bare koinConfiguration / koinApplication / startKoin no longer bypass A3 — the full-graph pass runs even without an explicit <T> type parameter.
• Cross-module DSL visibility under typed startKoin<T>() — A4 now sees DSL module { … } definitions declared in dependency JARs when the aggregator uses the typed entry point.

Incremental compilation & build robustness

• strictSafety flag — auto-enabled on modules that contain startKoin, koinApplication, or @KoinApplication. Forces the full-graph safety pass to re-run on the aggregator each build, working around two K2 IC gaps: DSL changes inside module { } lambda bodies (not part of any declaration's ABI) and @ComponentScan package-scope discovery (no source-level edge). Library and feature modules stay fully incremental.
• Module-disambiguated hint file names — stable anchors prevent cross-module Hints.kt collisions during multi-platform builds.
• kapt / Hilt coexistence — defensive guard around KtPsiSourceElement.psi prevents Fir2Ir crashes when the plugin runs alongside kapt or Hilt during migration.

Kotlin 2.3.20 compatibility

• Fir2Ir crash on K2.3.20 — HINTS_PACKAGE is now claimed unconditionally, fixing a regression when building against the latest K2.

Annotation fixes

• @Module(createdAtStart = true) — was silently ignored; now correctly forwards the flag to the generated module { }.
• @Scope(name = "…") — previously produced no bean definition; the scope DSL is now generated as expected.
• @ScopeId(name = "…") — resolution behaviour locked in via regression coverage.

Diagnostics

• CTA banner ordering — error reports anchor on the last error in the chain and use a per-extension collector, so the actionable hint is always closest to the offending call site.
• Compiler error info — error frames now embed the diagnostic code and a single-line "how to fix" pointer.

Performance

• Memoized startKoin module discovery — repeated scans during a single compilation reuse the resolved module set.
• Indexed @ComponentScan filtering — package-scope discovery now uses an indexed lookup instead of repeated linear scans, noticeably faster on large multi-module projects.

Repo / docs

• Playground apps moved into the main repo (playground-apps/app-dsl, playground-apps/app-annotations) — single clone, single build, no separate repo to keep in sync.
• Documentation updates — strictSafety, K2.3.20 minimum, circular-dep detection at compile time, KOIN-D007.

Behaviour changes to note when upgrading

strictSafety is on by default on aggregator modules. If your app contains startKoin, koinApplication, or @KoinApplication, that module's compileKotlin task will re-run the A3 safety pass on every build (library/feature modules unaffected). The cost is bounded, and it closes the IC gaps that previously let graph changes slip through cached builds. Set koinCompiler { strictSafety = false } to opt out.

Kotlin minimum bumped to 2.3.20 (was 2.3.0) — the Fir2Ir fix requires the newer compiler. If you're pinned to 2.3.0, stay on 1.0.0-RC2 until you can upgrade.

Closed issues since the project went public

Fixed

• #​1 — FileAnalysisException during compilation (@​FatalCatharsis)
• #​2 — Unrecognized @ScopeId (@​limuyang2)
• #​3 — Use a stable Kotlin version (@​adamglin0)
• #​7 — @Provided still flagging missing dependencies (@​kmbisset89)
• #​8 — Not generating a module (@​kmbisset89)
• #​11 — Incomplete IR type generation for Scope.get() (@​alex28sh)
• #​12 — Runtime stack overflow with Kotlin delegation pattern (@​pupava)
• #​14 — Generated .module() extension not recognized by IntelliJ (@​DenAbr)
• #​15 — Cannot fetch 0.6.1 version (@​FSBlocks)
• #​16 — Compiler crash on @Factory returning fun interface extending suspend function type (@​krzdabrowski) — now also blocked diagnostically via KOIN-D007
• #​17 — Incompatibility with Arrow core (@​gael-ft)
• #​18 — Compile-time safety breaks Native builds with generic types (@​alex-z0)
• #​20 — Duplicate callsite hint classes in multi-module builds (@​norbertsitko)
• #​22 — Compiler plugin misses cross-module bindings from @Single(binds = [...]) provider function (@​flaringapp)
• #​24 — IR crash on generic ViewModel base class on Kotlin/Native (iOS) (@​hmy65)
• #​29 — FileAnalysisException when migrating from Hilt (@​theimpulson)
• #​32 — compileSafety missing binding silently passes on incremental compilation (@​j-bajon) — drove the strictSafety design
• #​34 — @Scope(name=…) + @Scoped(binds=[…]) silently produce no bean definitions (@​rduriancik)
• #​35 — Module doesn't contain package org.koin.plugin.hints (@​0xMatthewGroves)
• #​38 — compileSafety checks bypassed when using KoinApplication Composable in CMP (@​rajdeepvaghela)

Won't fix / deferred

• #​21 — IDE cannot resolve generated module() extension (@​JordanLongstaff) — documented as a known limitation pending IDE-side support
• #​33 — Feature request: wasmJs target support (@​dmitry-stakhov) — tracked for a future release

Cross-repo fixes

• koin#2368 — @ScopeId(name = "…") resolution behaviour
• koin#2380 — typed startKoin<T> + @KoinApplication(modules=[…]) + scanned @KoinViewModel
• koin#2400 — nested DSL includes(...) reachability
• koin#2402 — explicit @KoinApplication(modules = [...]) overrides discovered @Configuration

Contributors

Project lead: @​arnaudgiuliani (Arnaud Giuliani)

Code contributions (commit authors and merged PRs across all releases):

• @​flaringapp — explicit bindings in @Module provider functions (PR #​23)
• @​JellyBrick — IR generation OOM fix (PR #​5), Gradle release signing fix (PR #​4)
• @​wjz2001 — cross-module @ComponentScan hints without @Configuration (PR #​25)
• Kevin Chiu — Gradle plugin package fix
• Youssef Shoaib — runtime annotations provider, build improvements
• @​Icyrockton
• Brian Norman
• Dmitriy Novozhilov
• Kengo TODA
• Roman Golyshev
• soarex

Credits for techniques:

• Zac Sweers — LookupTracker and ExpectActualTracker patterns from Metro

Issue reporters — the high-quality reproductions made all of this possible. See the closed-issues list above for the full set; everyone there contributed time and detail that shortened diagnosis significantly.

Internal feedback: Francois Dabonot (Kotzilla) — RC2.3 missing-artifact compile error came from his migration feedback.

Full changelog