repository·main·Indexed 27 days ago
https://github.com/insertkoinio/koinA pragmatic and lightweight dependency injection framework for Kotlin and Kotlin Multiplatform (KMP). Koin provides a powerful DSL and an annotation-driven approach, both supported by a dedicated compiler plugin that ensures compile-time safety for dependency graphs. It is compatible with JVM, Android, Compose, iOS, Desktop, Web (JS/Wasm), and Ktor. The framework supports dynamic module loading and offers an official IDE plugin for IntelliJ IDEA and Android Studio.
Koin provides Android-specific scopes to align dependency lifecycles with Android components. This prevents memory leaks and ensures proper resource management.
| Scope Type | Lifetime | Survives Rotation | DSL | Annotation |
|---|---|---|---|---|
| Application | Entire app | ✅ Yes | single { } | @Singleton |
| Activity | Activity lifecycle | ❌ No | activityScope { } | @ActivityScope |
| Activity Retained | Until finish() | ✅ Yes | activityRetainedScope { } | @ActivityRetainedScope |
| Fragment | Fragment lifecycle | ❌ No | fragmentScope { } | @FragmentScope |
| ViewModel | ViewModel lifecycle | ✅ Yes | viewModelScope { } | @ViewModelScope |
Child scopes can access parent scope definitions, but parents cannot access child scopes:
Application Scope $\rightarrow$ Activity Retained Scope $\rightarrow$ Activity Scope $\rightarrow$ Fragment Scope.
Note: ViewModel Scope can access parent scopes but cannot access Activity or Fragment scopes to prevent memory leaks.
The Koin Compiler Plugin validates your dependency graph at three distinct levels during compilation to catch missing dependencies, qualifier mismatches, and broken call sites before runtime.
@Module(includes = [...])), and sibling modules sharing the same @Configuration label.startKoin<T>(), including cross-module dependencies and definitions from external JARs.koinViewModel<T>(), get<T>(), and inject<T>() call to ensure the requested type T exists in the assembled graph, providing exact file, line, and column numbers on failure.Koin offers two primary ways to define dependencies, both of which are first-class citizens and fully supported by the Koin Compiler Plugin for compile-time safety.
Use the Kotlin DSL for a pure Kotlin approach. This is useful for developers who prefer explicit module definitions.
Use annotations for a more familiar pattern (similar to Hilt or Dagger) with less ceremony. This style is ideal for automatic component scanning and module discovery.
// DSL Style
val appModule = module {
single<Database>()
single<ApiClient>()
single<UserRepository>()
viewModel<UserViewModel>()
}
// Annotation Style
@Singleton
class Database
@Singleton
class ApiClient
@Singleton
class UserRepository(
private val database: Database,
private val apiClient: ApiClient
)
@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()Key takeaways for implementing instrumented tests with Koin in Android:
override = true or provide test-specific modules to replace production dependencies.KoinContext allows Koin to work seamlessly with Jetpack Compose testing.verify() (runtime) to catch configuration errors early.Koin provides two primary ways to define dependencies. You can choose based on your preference for a Kotlin DSL or a more annotation-driven style:
single<T>(), factory<T>(), and viewModel<T>().@Singleton, @Factory, and @KoinViewModel. It auto-detects dependencies and provides compile-time safety.singleOf(::MyService) or single { MyService(get()) }. This is fully supported and works with any Kotlin version.Note: The KSP Processor (koin-ksp-compiler) is deprecated. You should migrate to the Koin Compiler Plugin.
Dependency Injection is a design pattern where objects receive their dependencies from external sources rather than creating them internally. This promotes loose coupling, better testability, and cleaner architecture.
Activity, Fragment, or Service) where you do not control the constructor.Koin's core dependency resolution is R8-safe. Functions like get<T>(), inject<T>(), and the *Of builders (e.g., singleOf, factoryOf, viewModelOf) resolve dependencies at compile time using reified types. On Android/JVM, Koin keys the registry by Class.getName(), which is stable under R8.
Because Koin does not use runtime reflection over your constructors, you do not need to add ProGuard -keep rules for your Koin definitions, ViewModels, or their constructors on Koin's behalf. Koin automatically ships consumer-rules.pro in its Android AARs to handle its own internals.
The Koin Compiler Plugin offers several ways to interact with the dependency injection framework:
Koin uses different definition types to manage the lifecycle and creation of dependencies. Choose the type based on your use case:
| Type | DSL | Annotation | Lifecycle | Use Case |
|---|---|---|---|---|
| Singleton | single() | @Singleton | One instance for app lifetime | Services, repositories, databases |
| Factory | factory() | @Factory | New instance each time | Presenters, use cases, stateful objects |
| Scoped | scoped() | @Scoped | One instance per scope | Activity-bound, session-bound objects |
| ViewModel | viewModel() | @KoinViewModel | Android ViewModel lifecycle | ViewModels |
Select a starting method based on your application type:
startKoin { }: Use for standard applications. This registers Koin in the GlobalContext.koinApplication { }: Use for testing or building SDKs where you need an isolated Koin instance.koinConfiguration { }: Use for configuration within Compose or Ktor.startKoin<T>(): Use for typed startup when using the Koin Compiler Plugin.