# Technical Documentation: InsertKoinIO/koin
> โน๏ธ **Provenance:** Multi-Tier Ingestion ยท [CodeWiki Reference](https://codewiki.google/github.com/InsertKoinIO/koin)
### Overview (`README.md`)
[](https://kotlinlang.org)
[](https://github.com/InsertKoinIO/koin/blob/main/LICENSE.txt)
[](https://kotlinlang.slack.com/messages/koin/)
# What is KOIN? โจ
Koin is a pragmatic, lightweight dependency injection framework for Kotlin developers, developed by [Kotzilla](https://kotzilla.io) and open-source [contributors](https://github.com/InsertKoinIO/koin/graphs/contributors).
```
The pragmatic Kotlin & Kotlin Multiplatform Dependency Injection framework
- Simple, Powerful and now Compile-Safe -
```
## Compile-Safe Dependency Injection ๐ก๏ธ
Koin is now **compile-safe** thanks to the [Koin Compiler Plugin](https://github.com/InsertKoinIO/koin-compiler-plugin). Your dependency graph is verified at compile time โ missing bindings, broken definitions, and misconfigured modules are caught by the compiler instead of crashing at runtime.
- Catch missing or invalid dependencies before you run your app
- Keep Koin's concise, idiomatic DSL โ no extra boilerplate
- Works across Kotlin & Kotlin Multiplatform targets
Get started with the [Koin Compiler Plugin](https://github.com/InsertKoinIO/koin-compiler-plugin).
## Setup & Current Version ๐ฆ
Follow the dedicated [setup page](https://insert-koin.io/docs/setup/koin) to setup Koin for your project.
Here are the currently available Koin versions:
- **Latest** Version : [](https://mvnrepository.com/artifact/io.insert-koin/koin-core)
## Developer Tools & Observability ๐ ๏ธ
### Koin Skills โ for AI Coding Agents
Official [Koin skills](https://github.com/InsertKoinIO/koin-skills) teach your coding agent to set up Koin, write Koin code, migrate from Hilt, Dagger, Toothpick, Kodein, Metro or older Koin, and diagnose Koin apps, following the Koin Compiler Plugin rules.
```
# Claude Code
/plugin marketplace add InsertKoinIO/koin-skills
/plugin install koin@koin-skills
# Cursor, Codex, Copilot and other agents
npx skills add InsertKoinIO/koin-skills
```
Both commands install from the [koin-skills repository](https://github.com/InsertKoinIO/koin-skills) on GitHub (`npx skills` needs Node.js 22+). See [AI Agents and Koin Skills](https://insert-koin.io/docs/tooling/ai-agents).
### Kotzilla Platform โ KMP Crash Reporting & Observability
Free signup on [Kotzilla](https://kotzilla.io)
> The full observability platform for Kotlin Multiplatform apps:
> - **Full KMP Crash Reporting** โ complete crash reports across Android, iOS and all KMP targets
> - **Screen Rendering Impact** โ understand how each screen affects rendering and user experience
> - **Performance Monitoring** โ track runtime performance, memory metrics, and Koin module behavior
>
> A console-based suite with connected cloud services that visualizes your Koin module structure, provides advanced debugging and tracing, and seamlessly integrates with Kotlin Multiplatform projects.
### Koin IDE Plugin โ Your Koin Developer Assistant
Freely available on the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/26131-koin-dependency-injection-official-/versions/stable)
> The perfect Koin developer assistant: native support for IntelliJ IDEA and Android Studio, with navigation, inspections, and productivity features dedicated to Koin across Kotlin and Kotlin Multiplatform projects.
## Community & Enterprise Support ๐ฌ
Koin is backed by an active open-source community and by Kotzilla for teams that need guaranteed, enterprise-grade support.
### Community Support ๐ฑ
Free, open-source support from the Koin community:
- Chat with us on the Kotlin Slack [#koin](https://kotlinlang.slack.com/?redir=%2Fmessages%2Fkoin) channel
- Ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/koin) with the `koin` tag
- Found a bug or have a feature request? Open an issue on [GitHub](https://github.com/InsertKoinIO/koin/issues)
- Follow releases and announcements on the [Koin blog](https://blog.insert-koin.io) and [@insertkoin_io](https://twitter.com/insertkoin_io)
### Enterprise-Grade Support with Koin LTS ๐ข
For teams with production and compliance requirements, [**Koin LTS**](https://kotzilla.io/koin-lts) delivers enterprise-grade support backed by Kotzilla:
- **SLA-backed updates** and guaranteed response times
- **Long-term maintenance** on stabilized Koin versions (e.g. Koin 3.5 LTS)
- **Security & compliance patches** aligned with enterprise requirements
- **Direct access to Kotzilla experts** โ the team behind Koin
- **Priority bug fixes** and advisory support for architecture and migration
๐ Learn more and opt in at [kotzilla.io/koin-lts](https://kotzilla.io/koin-lts).
## Latest News & Resources ๐
- Official Website: [insert-koin.io](https://insert-koin.io)
- Twitter: [@insertkoin_io](https://twitter.com/insertkoin_io)
- Blog: [Koin Developers](https://blog.insert-koin.io)
## Contributing ๐
Want to help or share a proposal about Koin? Problem with a specific feature?
- Open an issue to explain the issue you want to solve [Open an issue](https://github.com/InsertKoinIO/koin/issues)
- Come talk on slack [#koin-dev](https://kotlinlang.slack.com/?redir=%2Fmessages%2Fkoin-dev) channel
- After discussion to validate your ideas, you can open a PR or even a draft PR if the contribution is a big one [Current PRs](https://github.com/InsertKoinIO/koin/pulls)
Additional readings about basic setup: https://github.com/InsertKoinIO/koin/blob/master/CONTRIBUTING.adoc
### Contributors
Thank you all for your work! โค๏ธ
## OpenCollective - Sponsorship โค๏ธ
Support this project by becoming a sponsor and be displayed on the offcial website. [[Help us and Become a sponsor!](https://opencollective.com/koin#sponsor)]
---
### Intro Index (`docs/intro/index.md`)
---
title: Introduction
---
# Welcome to Koin
**The Pragmatic Kotlin Dependency Injection Framework - Simple AND Powerful**
Koin is a lightweight dependency injection framework for Kotlin developers. Whether you're building Android apps, Kotlin Multiplatform projects, backend services with Ktor, or any Kotlin application, Koin makes dependency injection straightforward and intuitive.
## Why Koin?
Koin was designed with a clear philosophy: **you shouldn't have to choose between simplicity and capability**. With Koin, you get both.
### DSL & Annotations - Choose What You Want
Koin is powerful with both approaches. Prefer a clean Kotlin DSL? Use it. Like annotations? Use them. Both are first-class citizens, equally powerful.
| Value | What it means |
|-------|---------------|
| **Productive** | Easy to learn, easy to write. Get DI working in minutes, not hours |
| **Developer-Friendly** | DSL or Annotations - your choice. Clear errors, easy debugging, best DX |
| **Scalable** | Powers large enterprise applications with complex dependency graphs |
| **Safe** | Compile-time safety with Koin Compiler Plugin |
| **Dynamic** | Runtime flexibility: load modules dynamically, lazy loading, feature flags |
## Where to Start?
Choose your path based on your experience level:
### New to Dependency Injection?
Start with the fundamentals:
- **[What is Dependency Injection?](/docs/intro/what-is-dependency-injection)** - Understand the core concepts
### Know DI, New to Koin?
Jump right into Koin:
- **[What is Koin?](/docs/intro/what-is-koin)** - Discover Koin's approach to DI
- **[Koin Compiler Plugin](/docs/intro/koin-compiler-plugin)** - The recommended, safer way to use Koin
### Coming from Hilt/Dagger?
See how Koin compares:
- **[Koin vs Hilt/Dagger](/docs/intro/koin-vs-hilt)** - Understand the differences and migration path
### Ready to Code?
- **[Setup Guide](/docs/setup/gradle)** - Add Koin to your project
- **[Tutorials](/docs/tutorials/your-first-app)** - Build your first Koin app
- **[Koin IDE Plugin](https://plugins.jetbrains.com/plugin/26131-koin-dependency-injection-official-)** - Install the official plugin for Android Studio & IntelliJ IDEA โ code navigation, live safety checks, dependency graph visualization
## Koin's Approaches
Koin offers flexibility in how you define your dependencies:
| Approach | Status | Description |
|----------|--------|-------------|
| **Koin Compiler Plugin** (Kotlin 2.x) | Recommended | DSL: `single()`, `factory()`, `viewModel()`. |
| **Koin Compiler Plugin** (Kotlin 2.x) | Recommended | Annotations: `@Singleton`, `@Factory`, `@KoinViewModel`. Auto-detects dependencies, compile-time safety. |
| **Classic DSL** | Fully Supported | `singleOf(::MyService)`, `single { MyService(get()) }`. Works with any Kotlin version. Compiler Plugin adds safety on top when you're ready. |
| **KSP Processor** (`koin-ksp-compiler`) | Deprecated | Legacy processor for Koin Annotations. Migrate to Compiler Plugin โ same annotations, native compiler integration. |
Learn more in [What is Koin?](/docs/intro/what-is-koin) and [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin).
## Platform Support
Koin works everywhere Kotlin runs:
| Platform | Package | Status |
|----------|---------|--------|
| **Kotlin/JVM** | `koin-core` | โ
Full support |
| **Android** | `koin-android` | โ
Full support |
| **Compose (Android & Multiplatform)** | `koin-compose` | โ
Full support |
| **iOS** | `koin-core` | โ
Full support |
| **Desktop** | `koin-core` | โ
Full support |
| **Web (JS/Wasm)** | `koin-core` | โ
Full support |
| **Ktor** | `koin-ktor` | โ
Full support |
## Quick Example
Here's a taste of what Koin looks like:
```kotlin
// Define your classes
class UserRepository(private val api: ApiService)
class UserViewModel(private val repository: UserRepository) : ViewModel()
// Define your module with Compiler Plugin DSL
val appModule = module {
single()
single()
viewModel()
}
// Start Koin
startKoin {
modules(appModule)
}
// Inject in your Activity
class MainActivity : AppCompatActivity() {
private val viewModel: UserViewModel by viewModel()
}
```
Or with annotations:
```kotlin
@Singleton
class UserRepository(private val api: ApiService)
@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()
@Module
@ComponentScan("com.myapp")
class AppModule
```
Ready to get started? Head to the [Setup Guide](/docs/setup/gradle).
---
### Setup Index (`docs/setup/index.md`)
---
title: Setup & Versions
---
# Setting Up Koin
This guide covers everything you need to add Koin to your project.
## Quick Setup
Choose your platform to get started:
| Platform | Package | Guide |
|----------|---------|-------|
| **Kotlin/JVM** | `koin-core` | [Gradle Setup](/docs/setup/gradle#kotlin) |
| **Android** | `koin-android` | [Gradle Setup](/docs/setup/gradle#android) |
| **Android + Jetpack Compose** | `koin-android` + `koin-compose` | [Gradle Setup](/docs/setup/gradle#compose-android) |
| **Compose Multiplatform** | `koin-compose` | [Gradle Setup](/docs/setup/gradle#compose) |
| **Kotlin Multiplatform** | `koin-core` | [Gradle Setup](/docs/setup/gradle#kotlin-multiplatform) |
| **Ktor** | `koin-ktor` | [Gradle Setup](/docs/setup/gradle#ktor) |
## Recommended Setup: BOM + Compiler Plugin
For the best experience, we recommend:
1. **Use the Koin BOM** - Manages all Koin library versions
2. **Use the Koin Compiler Plugin** - Provides compile-time safety
See the **[Compiler Plugin Setup Guide](/docs/setup/compiler-plugin)** for detailed instructions.
## Setup Guides
### [Gradle Setup](/docs/setup/gradle)
Complete dependency configuration for all platforms:
- Koin BOM (recommended)
- Version catalogs
- Platform-specific packages
- Testing dependencies
### [Compiler Plugin Setup](/docs/setup/compiler-plugin)
Detailed guide for the Koin Compiler Plugin:
- Gradle plugin configuration
- Configuration options
- Kotlin version requirements
- Troubleshooting
### [KSP Processor Setup](/docs/setup/annotations-ksp) (Deprecated)
Legacy setup for `koin-ksp-compiler`, the KSP-based processor for Koin Annotations:
- โ ๏ธ `koin-ksp-compiler` is deprecated โ migrate to the Koin Compiler Plugin
- Koin Annotations itself is **not** deprecated; `koin-annotations` is now part of the main Koin project
- Migration guide included
## Version Compatibility
| Koin Version | Kotlin Version | Koin Compiler Plugin |
|--------------|----------------|----------------------|
| 4.2.x | 2.3+ | โ
Recommended |
| 4.1.x | 2.1/2.2+ | โ ๏ธ KSP Processor only |
| 4.0.x | 1.9/2.0+ | โ ๏ธ KSP Processor only |
| 3.5.x | 1.8+ | โ Not available |
## Current Version
- **Koin**: [](https://mvnrepository.com/artifact/io.insert-koin/koin-core)
- **Koin Compiler Plugin**: [](https://mvnrepository.com/artifact/io.insert-koin/koin-compiler-plugin)
Find all Koin packages on [Maven Central](https://central.sonatype.com/search?q=io.insert-koin+koin-core&sort=name).
## Next Steps
After setup:
- **[Core Concepts](/docs/reference/koin-core/starting-koin)** - Learn how to use Koin
- **[Tutorials](/docs/quickstart/kotlin)** - Build your first app
- **[Android Integration](/docs/reference/koin-android/start)** - Android-specific features
---
### Intro Koin Compiler Plugin (`docs/intro/koin-compiler-plugin.md`)
---
title: Koin Compiler Plugin
---
# Koin Compiler Plugin
The **Koin Compiler Plugin** is the recommended approach for all new Kotlin 2.x projects. It's a native Kotlin compiler plugin that powers both **DSL and Annotations** with auto-wiring, compile-time safety, and cleaner syntax.
## What is the Compiler Plugin?
The Koin Compiler Plugin is a **native Kotlin Compiler Plugin (K2)** - not KSP or annotation processing. It integrates directly with the Kotlin compiler to:
- **Auto-detect constructor parameters** - No manual `get()` calls needed
- **Transform code at compile-time** - Errors caught during build
- **Work with both DSL and Annotations** - Your choice of style
- **Generate no visible files** - Cleaner project structure
## Why Use the Compiler Plugin?
### 1. Safer Code
The plugin auto-detects constructor dependencies, reducing manual wiring errors:
```kotlin
// Without Compiler Plugin - easy to make mistakes
val appModule = module {
single { UserService(get(), get(), get()) } // Hope you got the order right!
}
// With Compiler Plugin - auto-wired
val appModule = module {
single() // Plugin detects all constructor parameters
}
```
### 2. Cleaner Syntax
Less boilerplate, more readable:
| Classic DSL | Compiler Plugin DSL |
|-------------|---------------------|
| `singleOf(::MyService)` | `single()` |
| `single { MyService(get(), get()) }` | `single()` |
| `factoryOf(::MyRepo)` | `factory()` |
| `viewModelOf(::MyVM)` | `viewModel()` |
| `scopedOf(::MyPresenter)` | `scoped()` |
| `workerOf(::MyWorker)` | `worker()` |
### 3. Compile-Time Safety
The Koin Compiler Plugin provides **compile-time dependency verification** for both DSL and Annotations:
- **A2 โ Per-Module:** validates definitions against visible scope (early feedback)
- **A3 โ Full Graph:** validates the complete assembled graph at `startKoin()`
- **A4 โ Call-Site:** validates every `get()`, `inject()`, `koinViewModel()` call
If it compiles, every dependency and every injection call site is satisfied. This replaces `verify()` and `checkModules()` โ no runtime test harness needed.
See [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety) for full details.
### 4. DSL & Annotations - Both Equally Powerful
Use whichever style you prefer - the same plugin powers both with identical capabilities:
**DSL Style:**
```kotlin
val appModule = module {
single()
single()
viewModel()
}
```
:::info DSL + Parameter Annotations
When using DSL style, you still use **parameter annotations** on your classes to guide the plugin:
```kotlin
class UserPresenter(
@InjectedParam val userId: String, // Runtime parameter
@Named("api") val client: ApiClient, // Qualified dependency
val repository: UserRepository // Auto-resolved
)
val appModule = module {
factory() // Plugin reads annotations from the class
}
```
The DSL defines **where** dependencies are registered. Parameter annotations define **how** they are resolved.
:::
**Annotation Style:**
```kotlin
@Singleton
class Database
@Singleton
class UserRepository(private val database: Database)
@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()
```
## Getting Started
### Setup
Add the Compiler Plugin to your project.
:::info
See the **[Compiler Plugin Setup Guide](/docs/setup/compiler-plugin)** for detailed instructions.
:::
### Using the Compiler Plugin DSL
Import from the compiler plugin package:
```kotlin
import org.koin.plugin.module.dsl.*
import org.koin.dsl.module
val appModule = module {
single()
single()
single()
viewModel()
}
```
:::note
The Compiler Plugin DSL is in `org.koin.plugin.module.dsl`. Classic DSL remains in `org.koin.dsl`.
:::
### Using Annotations
Annotations work the same as before:
```kotlin
@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()
@Module
@ComponentScan("com.myapp")
class AppModule
```
## How It Works
The Compiler Plugin operates in two phases:
### 1. FIR Phase (Analysis)
During the Frontend Intermediate Representation phase, the plugin:
- Analyzes your module definitions
- Detects constructor parameters
- Validates dependency declarations
### 2. IR Phase (Transformation)
During the Intermediate Representation phase, the plugin:
- Generates proper `get()` calls for each parameter
- Handles qualifiers (`@Named`)
- Handles injected parameters (`@InjectedParam`)
- Handles nullable and Lazy types
### What Gets Generated
When you write:
```kotlin
single()
```
The plugin transforms it to:
```kotlin
single { UserRepository(get(), get()) } // Parameters auto-detected
```
For more complex cases:
```kotlin
// Your code
@Singleton
class MyService(
val required: RequiredDep,
val optional: OptionalDep?,
@Named("special") val named: NamedDep,
val lazy: Lazy,
@InjectedParam val param: String
)
```
The plugin generates proper handling for each parameter type:
- Required: `get()`
- Optional: `getOrNull()`
- Named: `get(named("special"))`
- Lazy: `inject()`
- InjectedParam: `params.get()`
## Compiler Plugin DSL Reference
### Definition Types
```kotlin
import org.koin.plugin.module.dsl.*
val appModule = module {
// Singleton - one instance
single()
// Factory - new instance each time
factory()
// Scoped - instance per scope
scope {
scoped()
}
// ViewModel
viewModel()
// Worker (Android WorkManager)
worker()
}
```
### Safe Instance Creation with `create()`
Use `create(::T)` inside a definition lambda to safely build an instance with auto-resolved constructor dependencies:
```kotlin
val appModule = module {
single { create(::MyService) }
}
```
The compiler plugin transforms `create(::MyService)` into `MyService(get(), get(), ...)`, auto-wiring all constructor parameters.
### With Qualifiers
Use `@Named` on your classes to define qualifiers, and on parameters to specify which dependency to inject:
```kotlin
// Define implementations with @Named qualifier
@Named("local")
class LocalDatabase : Database
@Named("remote")
class RemoteDatabase : Database
// Use @Named on parameters to specify which one to inject
class SyncService(
@Named("local") val localDb: Database,
@Named("remote") val remoteDb: Database
)
// DSL - plugin reads @Named from classes and parameters
val appModule = module {
single()
single()
single()
}
```
You can also create custom qualifiers with `@Qualifier`:
```kotlin
@Qualifier
annotation class LocalDb
@Qualifier
annotation class RemoteDb
@LocalDb
class LocalDatabase : Database
@RemoteDb
class RemoteDatabase : Database
class SyncService(
@LocalDb val localDb: Database,
@RemoteDb val remoteDb: Database
)
```
### With Parameters
Use `@InjectedParam` on your class to mark parameters passed at injection time:
```kotlin
// Annotation on the class - tells the plugin how to handle this parameter
class UserPresenter(
@InjectedParam val userId: String, // Passed via parametersOf()
val repository: UserRepository // Auto-resolved by Koin
)
// DSL in module - tells Koin where to register
val appModule = module {
factory()
}
// Usage - pass the runtime parameter
val presenter: UserPresenter = get { parametersOf("user123") }
```
### Interface Binding
```kotlin
val appModule = module {
single() bind UserRepository::class
// Or multiple bindings
single() binds arrayOf(
ServiceA::class,
ServiceB::class
)
}
```
## Annotations Reference
### Definition Annotations
| Annotation | Description |
|------------|-------------|
| `@Singleton` / `@Single` | Single instance |
| `@Factory` | New instance each time |
| `@Scoped` | Instance per scope |
| `@KoinViewModel` | Android ViewModel |
| `@KoinWorker` | Android WorkManager Worker |
### Parameter Annotations
| Annotation | Description |
|------------|-------------|
| `@Named("qualifier")` | Named qualifier |
| `@InjectedParam` | Runtime parameter (via `parametersOf()`) |
| `@Property("key")` | Koin property value |
| `@Provided` | External dependency (skip validation) |
### Module Annotations
| Annotation | Description |
|------------|-------------|
| `@Module` | Declares a Koin module |
| `@ComponentScan("package")` | Scan package for annotated classes |
| `@Configuration` | Auto-discovered module |
## Comparison: Approaches
| Approach | Status | Package | Syntax |
|----------|--------|---------|--------|
| **Compiler Plugin DSL** | Recommended | Already located in Koin **`org.koin.plugin.module.dsl`** | `single()`, `factory()`, `viewModel()` |
| **Compiler Plugin Annotations** | Recommended | Annotations available in **`koin-annotations`** | `@Singleton`, `@Factory`, `@KoinViewModel ` |
| **Classic DSL** | Fully Supported | `org.koin.dsl` | `singleOf(::MyService)`, `single { MyService(get()) }`, `viewModelOf(::MyVM)` |
| **KSP Processor** | Deprecated | `koin-ksp-compiler` | Legacy processor for Koin Annotations โ same annotations, **Migrate to Compiler Plugin โ ๏ธ** |
### Compiler Plugin DSL (Recommended)
- Auto-detects dependencies
- Compile-time analysis
- Cleanest syntax
### Compiler Plugin Annotations (Recommended)
- Auto-detects dependencies
- Compile-time analysis
- Familiar annotation style
### Classic DSL (Fully Supported)
- Works with any Kotlin version
- Full control over wiring
- Can migrate to Plugin DSL when ready
### KSP Processor `koin-ksp-compiler` (Deprecated)
- The `koin-annotations` library is **not deprecated** โ it's now part of the Koin project
- Only the legacy KSP-based processor (`koin-ksp-compiler`) is deprecated
- Migrate to the Koin Compiler Plugin โ your annotations stay the same
- `koin-ksp-compiler` will be removed in a future Koin version
## Migration
### From Classic DSL
If you're using classic DSL, migration is optional but recommended:
1. Add the Compiler Plugin to Gradle
2. Update imports to `org.koin.plugin.module.dsl.*`
3. Replace `singleOf(::Class)` with `single()`
4. Remove manual `get()` calls
See the [Compiler Plugin DSL reference](/docs/setup/compiler-plugin#dsl-style) for the compile-time safe syntax.
### From the KSP Processor (`koin-ksp-compiler`)
If you're using Koin Annotations with the legacy KSP processor, migration is recommended now:
1. Update Kotlin to 2.x
2. Replace `koin-ksp-compiler` with the Koin Compiler Plugin
3. **Your annotations stay the same** โ no code changes!
4. Delete generated files
See [Migrating from KSP to Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin).
## Requirements
- **Kotlin 2.x** (K2 compiler)
- Gradle 8.x+
## Configuration Options
```kotlin
// build.gradle.kts
koinCompiler {
// Options will be documented here
}
```
## Classic DSL: Still Fully Supported
The Compiler Plugin doesn't replace Classic DSL - it adds analysis and generation on top. Classic DSL remains fully supported:
```kotlin
// Still works perfectly
val appModule = module {
singleOf(::Database)
singleOf(::ApiClient)
single { CustomService(get(), get(), configValue) } // Custom logic
viewModelOf(::UserViewModel)
}
```
Use Classic DSL when you need:
- Custom factory logic
- `getOrNull()` for optional dependencies
- Conditional instantiation
- Backward compatibility with Kotlin 1.x
## Next Steps
- **[Setup Guide](/docs/setup/compiler-plugin)** - Detailed setup instructions
- **[DSL Reference](/docs/reference/dsl-reference)** - Complete DSL documentation
- **[Annotations Reference](/docs/reference/annotations-reference)** - Complete annotations documentation
- **[Migration Guides](/docs/migration/from-ksp-to-compiler-plugin)** - Upgrade your project
---
### Intro Koin Vs Hilt (`docs/intro/koin-vs-hilt.md`)
---
title: Koin vs Hilt/Dagger
---
# Koin vs Hilt/Dagger
This page compares Koin with Hilt and Dagger to help you understand the differences and decide which framework fits your needs.
:::info
Koin supports both **DSL and Annotations** - choose what fits your team. Both are first-class citizens, equally powerful, and powered by the same Compiler Plugin. This comparison shows annotation examples for fair comparison with Hilt, but Koin's DSL offers equivalent functionality with even less boilerplate.
:::
## Philosophy Differences
| Aspect | Koin | Hilt/Dagger |
|--------|------|-------------|
| **Learning curve** | Minutes to learn | Hours/days to master |
| **Code complexity** | Simple DSL or annotations | Complex annotation rules |
| **Debugging** | Clear errors, no generated code maze | Generated code can be hard to trace |
| **Setup** | One plugin, minimal config | Multiple annotations, strict rules |
| **Compile safety** | โ
With Compiler Plugin | โ
Always |
| **Runtime flexibility** | โ
Dynamic features | โ Static only |
## Annotation Comparison
Even annotations are simpler in Koin:
| Task | Koin | Hilt |
|------|------|------|
| **Singleton** | `@Singleton class MyService` | `@Singleton class MyService @Inject constructor(...)` |
| **Interface binding** | Automatic | Requires `@Binds` in abstract module |
| **Component scanning** | `@ComponentScan("package")` | Not available |
| **Module discovery** | `@Configuration` - auto-discovered | Manual `@InstallIn` per module |
| **Provide 3rd party** | `@Singleton fun provide()` | `@Provides` in `@Module` + `@InstallIn` |
| **ViewModel** | `@KoinViewModel class MyVM` | `@HiltViewModel class MyVM @Inject constructor` |
## Code Comparison
### Simple Singleton
**Koin:**
```kotlin
@Singleton
class MyRepository(val api: ApiService)
@Module
@ComponentScan("com.app")
class AppModule
```
**Hilt:**
```kotlin
@Singleton
class MyRepository @Inject constructor(val api: ApiService)
@Module
@InstallIn(SingletonComponent::class)
abstract class AppModule {
@Binds
abstract fun bindRepository(impl: MyRepository): Repository
}
```
### Interface Binding
**Koin - Automatic:**
```kotlin
@Singleton
class UserRepositoryImpl(val db: Database) : UserRepository
// That's it! Koin automatically binds to UserRepository interface
```
**Hilt - Requires explicit binding:**
```kotlin
@Singleton
class UserRepositoryImpl @Inject constructor(val db: Database) : UserRepository
@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {
@Binds
abstract fun bindUserRepository(impl: UserRepositoryImpl): UserRepository
}
```
### Multi-Module Apps
**Koin - Modules auto-discovered:**
```kotlin
// feature/auth/AuthModule.kt
@Module
@ComponentScan
@Configuration // Auto-discovered!
class AuthModule
// feature/profile/ProfileModule.kt
@Module
@ComponentScan
@Configuration // Auto-discovered!
class ProfileModule
// app/MyApp.kt
@KoinApplication // No need to list modules
class MyApp
```
**Hilt - Must manually install each module:**
```kotlin
// feature/auth/AuthModule.kt
@Module
@InstallIn(SingletonComponent::class)
class AuthModule { ... }
// feature/profile/ProfileModule.kt
@Module
@InstallIn(SingletonComponent::class)
class ProfileModule { ... }
// app/MyApp.kt
@HiltAndroidApp
class MyApp // Still need correct @InstallIn everywhere
```
### ViewModel
**Koin:**
```kotlin
@KoinViewModel
class UserViewModel(
private val repository: UserRepository,
private val savedStateHandle: SavedStateHandle
) : ViewModel()
// In Activity/Fragment
val viewModel: UserViewModel by viewModel()
// In Compose
val viewModel: UserViewModel = koinViewModel()
```
**Hilt:**
```kotlin
@HiltViewModel
class UserViewModel @Inject constructor(
private val repository: UserRepository,
private val savedStateHandle: SavedStateHandle
) : ViewModel()
// In Activity/Fragment
val viewModel: UserViewModel by viewModels()
// In Compose
val viewModel: UserViewModel = hiltViewModel()
```
### Providing Third-Party Libraries
**Koin:**
```kotlin
@Module
class NetworkModule {
@Singleton
fun provideRetrofit(): Retrofit = Retrofit.Builder()
.baseUrl("https://api.example.com")
.build()
@Singleton
fun provideApi(retrofit: Retrofit): ApiService =
retrofit.create(ApiService::class.java)
}
```
**Hilt:**
```kotlin
@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {
@Provides
@Singleton
fun provideRetrofit(): Retrofit = Retrofit.Builder()
.baseUrl("https://api.example.com")
.build()
@Provides
@Singleton
fun provideApi(retrofit: Retrofit): ApiService =
retrofit.create(ApiService::class.java)
}
```
## Dynamic Features: Koin's Unique Advantage
Koin is **runtime-based but performant and compile-safe**. This enables dynamic features that Hilt cannot offer:
| Dynamic Feature | Koin | Hilt |
|-----------------|------|------|
| Load modules at runtime | โ
`loadKoinModules()` | โ Not possible |
| Unload modules | โ
`unloadKoinModules()` | โ Not possible |
| Lazy background loading | โ
`lazyModules()` | โ Not possible |
| Feature flag injection | โ
Easy | โ ๏ธ Complex workarounds |
| Plugin architectures | โ
Natural fit | โ Very difficult |
| A/B test implementations | โ
Runtime swap | โ ๏ธ Compile-time only |
| Dynamic configuration | โ
Supported | โ No, Must recompile |
### Example: Dynamic Module Loading
```kotlin
// KOIN - Dynamic module loading
if (userHasPremium) {
loadKoinModules(premiumFeatureModule)
}
// Later, if subscription expires
unloadKoinModules(premiumFeatureModule)
// Lazy loading for faster startup
startKoin {
modules(coreModule)
lazyModules(
analyticsModule, // Loaded in background
heavyFeatureModule
)
}
```
**This is impossible with Hilt** - all dependencies are wired at compile time.
### Example: Feature Flags
```kotlin
// KOIN - Switch implementations at runtime
val featureModule = module {
if (FeatureFlags.useNewApi) {
single { NewApiService() }
} else {
single { LegacyApiService() }
}
}
// Or dynamically
fun updateApiImplementation(useNew: Boolean) {
unloadKoinModules(apiModule)
loadKoinModules(if (useNew) newApiModule else legacyApiModule)
}
```
## Setup Comparison
### Koin Setup
See the **[Compiler Plugin Setup Guide](/docs/setup/compiler-plugin)** for detailed instructions.
### Hilt Setup
```kotlin
// settings.gradle.kts
plugins {
id("com.google.dagger.hilt.android") version "2.x" apply false
}
// app/build.gradle.kts
plugins {
id("com.google.devtools.ksp")
id("dagger.hilt.android.plugin")
}
dependencies {
implementation("com.google.dagger:hilt-android:2.x")
ksp("com.google.dagger:hilt-compiler:2.x")
}
```
## Error Messages
### Koin
```
org.koin.core.error.NoBeanDefFoundException:
No definition found for class 'com.app.UserRepository'.
Check your module definitions.
```
Clear, points directly to the issue.
### Hilt/Dagger
```
error: [Dagger/MissingBinding] com.app.UserRepository cannot be provided
without an @Inject constructor or an @Provides-annotated method.
com.app.UserRepository is injected at
com.app.UserService(repository)
com.app.UserService is injected at
com.app.UserActivity.service
com.app.UserActivity is injected at
dagger.hilt.android.internal.managers.ActivityComponentManager.inject
```
Longer, requires understanding the component graph.
## When to Choose Each
### Choose Koin When:
- You value **productivity and simplicity**
- You need **runtime flexibility** (dynamic modules, feature flags)
- You're building **Kotlin Multiplatform** apps
- Your team wants to **learn quickly**
- You prefer **less boilerplate**
- You want **easier debugging**
### Choose Hilt When:
- Your team **already knows Dagger**
- You need **Google-first ecosystem** compatibility
- You require **Dagger's specific features**
## Migration from Hilt to Koin
If you're considering migration:
### Concept Mapping
| Hilt | Koin |
|------|------|
| `@HiltAndroidApp` | `@KoinApplication` and `startKoin { }` |
| `@AndroidEntryPoint` | `by inject()` |
| `@HiltViewModel` with `by viewModels()` | `@KoinViewModel` with `by viewModel()` |
| `@Inject constructor` | Just constructor (auto-detected) |
| `@Binds` | Automatic or `bind` |
| `@InstallIn(SingletonComponent)` | `@Configuration` |
| `@Provides` on a function | `@Factory` on a function |
### Gradual Migration
You can migrate incrementally:
1. Add Koin to your project
2. Migrate one feature module at a time
3. Both DI frameworks can coexist during transition (Koin can scan target packages with `@ComponentScan`)
4. Remove Hilt when migration is complete
See [Migrating from Hilt](/docs/migration/from-hilt) for detailed steps.
## Summary
**Koin: Simple AND Powerful**
- **Compile-time safety** like Hilt (with Compiler Plugin)
- **DSL or Annotations** - both equally powerful, your choice
- **Simplicity and productivity** that Hilt can't match
- **Dynamic runtime features** that Hilt can't do
You don't have to choose between safety and simplicity. With Koin, you get both.
## Next Steps
- **[What is Koin?](/docs/intro/what-is-koin)** - Learn more about Koin
- **[Setup Guide](/docs/setup/gradle)** - Add Koin to your project
- **[Migrating from Hilt](/docs/migration/from-hilt)** - Step-by-step migration guide
---
### Intro What Is Dependency Injection (`docs/intro/what-is-dependency-injection.md`)
---
title: What is Dependency Injection?
---
# What is Dependency Injection?
Dependency Injection (DI) 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 code architecture.
## What is a Dependency?
A dependency is any object that another object needs to function. For example, a `Car` depends on an `Engine` to drive.
### Without Dependency Injection
```kotlin
class Engine {
fun start() {
println("Engine starting...")
}
}
class Car {
private val engine = Engine() // Car creates its own engine
fun drive() {
engine.start()
println("Car is driving")
}
}
```
**Problems with this approach:**
- `Car` is tightly coupled to a specific `Engine` implementation
- Difficult to test `Car` independently
- Hard to swap engine types (electric, diesel, etc.)
- `Car` controls the lifecycle of `Engine`
### With Dependency Injection
```kotlin
class Car(private val engine: Engine) { // Engine is injected
fun drive() {
engine.start()
println("Car is driving")
}
}
// Now we can easily provide different engines
val gasolineCar = Car(GasEngine())
val electricCar = Car(ElectricEngine())
```
**Benefits:**
- `Car` doesn't know how `Engine` is created
- Easy to test with mock engines
- Flexible - can swap implementations
- Clear dependencies visible in constructor
## Three Ways to Provide Dependencies
### 1. Constructor Injection (Recommended)
Dependencies are passed through the constructor:
```kotlin
class UserRepository(
private val database: Database,
private val apiClient: ApiClient
) {
fun getUser(id: String): User {
return database.query(id) ?: apiClient.fetchUser(id)
}
}
```
**Advantages:**
- Dependencies are explicit and required
- Immutable (using `val`)
- Easy to test
- Clear dependency graph
**With Koin:**
```kotlin
val appModule = module {
single()
single()
single() // Koin auto-wires dependencies
}
```
:::info
Constructor injection is the **preferred approach** in Koin. It makes your code testable without requiring Koin in unit tests.
:::
### 2. Field Injection
Dependencies are injected into class properties:
```kotlin
class UserActivity : AppCompatActivity() {
// Lazy injection - instance created when first accessed
private val viewModel: UserViewModel by viewModel()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
viewModel.loadUser() // ViewModel instance created here
}
}
```
**When to use:**
- Android framework classes (Activity, Fragment, Service) where you don't control construction
- When constructor injection isn't possible
**With Koin:**
```kotlin
// Lazy injection
val presenter: Presenter by inject()
// Eager injection
val presenter: Presenter = get()
```
### 3. Method Injection
Dependencies are passed through methods (less common):
```kotlin
class ReportGenerator {
fun generateReport(data: DataSource) {
// Use data to generate report
}
}
```
**When to use:**
- Optional dependencies
- Dependencies that change during object lifetime
- Callback patterns
## Manual vs Automated Dependency Injection
### The Problem with Manual DI
As applications grow, managing dependencies manually becomes complex:
```kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Manually creating the entire dependency graph
val database = Database()
val apiClient = ApiClient()
val userRepository = UserRepository(database, apiClient)
val authRepository = AuthRepository(database, apiClient)
val userService = UserService(userRepository, authRepository)
val viewModel = UserViewModel(userService)
// Finally can use viewModel...
}
}
```
**Problems:**
- Repetitive code across Activities/Fragments
- Easy to make mistakes in dependency order
- Hard to maintain as the app grows
- Difficult to manage lifecycles (singletons, scoped objects)
- No centralized configuration
### The Container Pattern (Manual Approach)
Developers often create a container to centralize object creation:
```kotlin
object AppContainer {
private val database by lazy { Database() }
private val apiClient by lazy { ApiClient() }
val userRepository by lazy { UserRepository(database, apiClient) }
val authRepository by lazy { AuthRepository(database, apiClient) }
fun createUserViewModel() = UserViewModel(
UserService(userRepository, authRepository)
)
}
// Usage
class MainActivity : AppCompatActivity() {
private val viewModel = AppContainer.createUserViewModel()
}
```
**Still has issues:**
- Manual wiring of dependencies
- No automatic lifecycle management
- Global state (singleton container)
- Still repetitive for complex graphs
### How Koin Solves This
Koin provides automated dependency resolution with your choice of **DSL or Annotations**:
```kotlin
// Define dependencies once
val appModule = module {
single()
single()
single()
single()
single()
viewModel()
}
// Start Koin once
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
modules(appModule)
}
}
}
// Use anywhere - Koin handles the entire dependency graph
class MainActivity : AppCompatActivity() {
private val viewModel: UserViewModel by viewModel()
// That's it! Koin creates UserViewModel and all its dependencies
}
```
**Koin advantages:**
- Declarative dependency configuration
- Automatic dependency resolution
- Lifecycle management (singleton, factory, scoped)
- Type-safe injection
- Easy testing and module replacement
## Automated DI Solutions
There are different approaches to automated dependency injection:
| Approach | Examples | How it works |
|----------|----------|--------------|
| **Reflection-based** | (older frameworks) | Uses reflection at runtime |
| **Code generation** | Dagger, Hilt | Generates code at compile time (annotation processing) |
| **Compiler plugins** | Koin Compiler Plugin | Native compiler integration for DSL & Annotations |
| **DSL-based** | Koin (classic) | Runtime DSL configuration |
**Koin's approach - DSL & Annotations, both equally powerful:**
- **DSL style:** Clean Kotlin DSL configuration (`single()`, `viewModel()`)
- **Annotation style:** Familiar annotations (`@Singleton`, `@KoinViewModel`)
- Both powered by the same Compiler Plugin for compile-time safety
- No reflection, lightweight
- Choose the style that fits your team
## Service Locator vs Dependency Injection
It's important to understand the difference:
### Service Locator Pattern
Components actively request dependencies from a registry:
```kotlin
class UserService : KoinComponent {
private val repository: UserRepository by inject() // "Pulling" dependency
}
```
### Dependency Injection Pattern
Dependencies are provided from outside:
```kotlin
class UserService(
private val repository: UserRepository // "Pushed" into component
)
```
### Comparison
| Aspect | Service Locator | Dependency Injection |
|--------|----------------|---------------------|
| Dependency visibility | Hidden inside class | Explicit in constructor |
| Testing | Requires framework | Easy - pass test doubles |
| Coupling | Depends on container | Depends on interfaces |
| Usage in Koin | `get()`, `by inject()` | Constructor with Koin module |
| Best for | Android framework classes | Business logic, services |
### Best Practices with Koin
1. **Prefer Constructor Injection** for business logic:
```kotlin
// Good - testable without Koin
class UserViewModel(private val userService: UserService) : ViewModel()
val appModule = module {
viewModel() // Koin resolves dependencies
}
```
2. **Use Service Locator** only when necessary:
```kotlin
// Acceptable - Activity construction controlled by Android
class UserActivity : AppCompatActivity() {
private val viewModel: UserViewModel by viewModel()
}
```
3. **Avoid `KoinComponent` in business logic:**
```kotlin
// Bad - hard to test
class UserService : KoinComponent {
private val repository: UserRepository = get()
}
// Good - explicit dependencies
class UserService(private val repository: UserRepository)
```
## Benefits of Dependency Injection
### 1. Testability
Without DI, testing is difficult:
```kotlin
class UserService {
private val repository = UserRepository() // Can't mock!
}
```
With DI, testing is straightforward:
```kotlin
class UserService(private val repository: UserRepository)
@Test
fun testGetUser() {
val mockRepository = mockk()
val service = UserService(mockRepository) // Full control
every { mockRepository.findUser("123") } returns testUser
assertEquals(testUser, service.getUser("123"))
}
```
### 2. Flexibility
Easily swap implementations:
```kotlin
val appModule = module {
single { GmailService() } // Production
}
val testModule = module {
single { MockEmailService() } // Testing
}
```
### 3. Code Organization
Centralized dependency configuration:
```kotlin
val dataModule = module {
single()
single()
}
val domainModule = module {
single()
single()
}
val presentationModule = module {
viewModel()
}
startKoin {
modules(dataModule, domainModule, presentationModule)
}
```
### 4. Lifecycle Management
Koin handles object lifecycles:
```kotlin
val appModule = module {
single() // One instance for entire app
factory() // New instance each time
scoped() // Instance per scope
}
```
## Summary
Dependency Injection is a powerful pattern that:
- **Decouples** components from their dependencies
- **Improves testability** by allowing dependency replacement
- **Simplifies maintenance** with centralized configuration
- **Scales better** than manual dependency management
Koin makes DI in Kotlin simple by:
- Offering **two equally powerful styles**: DSL or Annotations - your choice
- Supporting both **constructor injection** (recommended) and **field injection** (when needed)
- Providing **compile-time safety** with the Compiler Plugin
- Requiring **zero reflection** - pure Kotlin
## Next Steps
- **[What is Koin?](/docs/intro/what-is-koin)** - Learn about Koin's approach
- **[Koin Compiler Plugin](/docs/intro/koin-compiler-plugin)** - The recommended, safer approach
- **[Setup Guide](/docs/setup/gradle)** - Add Koin to your project
---
### Intro What Is Koin Annotations (`docs/intro/what-is-koin-annotations.md`)
---
title: What is Koin Annotations?
---
# What is Koin Annotations?
### Familiar Annotation Style โ Part of the Main Koin Project
**Koin Annotations** is the annotation-based way to define your dependencies in Koin. If you prefer the style of `@Singleton`, `@Factory`, `@KoinViewModel` over a Kotlin DSL, this is for you.
It is **part of the main Koin project** โ same GitHub repository, same release cycle, same Koin version, same maintainers. Not a side project, not a community fork, not a separate framework. It's processed by the **Koin Compiler Plugin** for compile-time safety, just like the DSL.
## In a Nutshell
```kotlin
@Singleton
class UserRepository(private val api: ApiService)
@KoinViewModel
class UserViewModel(private val repository: UserRepository) : ViewModel()
@Module
@ComponentScan("com.myapp")
class AppModule
```
That's the whole idea: annotate your classes, declare a module, the Koin Compiler Plugin wires the rest at build time.
## Part of the Main Koin Project
The `koin-annotations` library is **part of the main Koin project**. It lives in the same repository, ships under the **same Koin version** as `koin-core`, follows the same release cycle, and is covered by the Koin BOM:
```kotlin
dependencies {
implementation(platform("io.insert-koin:koin-bom:$koin_version"))
implementation("io.insert-koin:koin-core")
implementation("io.insert-koin:koin-annotations") // same Koin version, same BOM
}
```
What this means in practice:
- **Not deprecated** โ annotations are a first-class, fully supported style
- **Not a separate product** โ there's no "Koin Annotations" project to track on its own
- **Versions stay in sync** โ `koin-core` and `koin-annotations` always match
- **Full feature parity with the DSL** โ anything you can do with the DSL, you can do with annotations
## Now Powered by the Koin Compiler Plugin
Koin Annotations is processed by the **Koin Compiler Plugin** โ a native **Kotlin Compiler Plugin (K2)** that integrates directly with the Kotlin compiler. No KSP, no generated files to commit, no extra processing step.
What you get:
- **Auto-wiring** โ constructor parameters are detected and resolved automatically
- **Compile-time safety** โ missing dependencies, qualifier mismatches, and bad bindings are caught at build time
- **Simpler KMP setup** โ no per-target KSP configuration
- **Same annotations** โ `@Singleton`, `@Factory`, `@KoinViewModel`, `@Module`, `@ComponentScan`, `@Named`, `@InjectedParam`, etc.
See [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin) for the full picture of how it works and what it generates.
## `koin-ksp-compiler` is Deprecated
:::warning
The legacy KSP processor `koin-ksp-compiler` is **deprecated** and will be removed in a future Koin version.
:::
The annotations themselves are **not** deprecated โ only the KSP-based processor that used to handle them. Migration is mechanical:
- **Same annotations** โ your `@Singleton`, `@Module`, `@ComponentScan` code stays exactly the same
- **Drop the KSP plugin** โ replace with the Koin Compiler Plugin
- **Delete generated files** โ the Compiler Plugin doesn't produce visible generated sources
See [Migrating from KSP to Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin) for the step-by-step.
## When to Choose Annotations
Both annotations and the DSL are first-class. Pick annotations if:
- You're coming from Hilt, Dagger, or Spring and want a familiar style
- You prefer co-locating the definition with the class it describes
- Your team standardizes on annotation-based configuration
Pick the DSL if you prefer a Kotlin-native, code-only style. You can also **mix both** in the same project โ they're processed by the same Compiler Plugin.
## Next Steps
- **[Koin Compiler Plugin](/docs/intro/koin-compiler-plugin)** โ How the plugin powers your annotations
- **[Annotations Reference](/docs/reference/koin-annotations/start)** โ Full annotation catalog and patterns
- **[Migrating from KSP to Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin)** โ Upgrade path from `koin-ksp-compiler`
- **[What is Koin?](/docs/intro/what-is-koin)** โ The bigger picture
---
### Intro What Is Koin (`docs/intro/what-is-koin.md`)
---
title: What is Koin?
---
# What is Koin?
### The Pragmatic Kotlin Dependency Injection Framework - Simple AND Powerful
Koin is a lightweight dependency injection framework designed specifically for Kotlin. Unlike traditional DI frameworks that rely on code generation or reflection, Koin offers two equally powerful approaches: a clean **Kotlin DSL** and intuitive **Annotations**. Choose what fits your team - both are first-class citizens.
## Koin's Core Values
| Value | What it means |
|-------|---------------|
| **Productive** | Easy to learn, easy to write. Get DI working in minutes, not hours |
| **Developer-Friendly** | DSL or Annotations - your choice. Clear errors, easy debugging, best DX |
| **Scalable** | Powers large enterprise applications with complex dependency graphs |
| **Safe** | Compile-time safety with Koin Compiler Plugin |
| **Dynamic** | Runtime flexibility: load modules dynamically, lazy loading, feature flags |
## Why Developers Love Koin
- **Learn in minutes** - No complex concepts, intuitive DSL and simple annotations
- **Write less code** - DSL or Annotations, Compiler Plugin auto-wires dependencies
- **Choose your style** - DSL for Kotlin purists, Annotations for familiar patterns - both equally powerful
- **Debug easily** - Clear error messages, no generated code to trace through
- **Scale confidently** - Used in production by enterprises worldwide
- **Stay safe** - Compile-time verification catches errors before runtime
- **Stay flexible** - Runtime-based but performant. Dynamic modules, lazy loading, feature flags
- **IDE support** - Official plugin for Android Studio & IntelliJ IDEA โ navigate definitions, live safety checks, graph visualization
## Two Styles, One Framework - Both Equally Powerful
Koin supports two styles of defining dependencies. Both are first-class citizens with full feature parity. Choose what fits your team:
### DSL Style
Define dependencies using Kotlin DSL syntax:
```kotlin
val appModule = module {
single()
single()
single()
viewModel()
}
```
### Annotation Style
Define dependencies using annotations:
```kotlin
@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()
```
Both styles are processed by the **Koin Compiler Plugin** for compile-time safety.
## Koin's Annotations Are Simpler
If you've used Hilt or Dagger, you'll notice Koin annotations require less ceremony:
| Task | Koin | Hilt |
|------|------|------|
| **Singleton** | `@Singleton class MyService` | `@Singleton class MyService @Inject constructor(...)` |
| **Interface binding** | Automatic (just implement the interface) | Requires `@Binds` in abstract module |
| **Component scanning** | `@ComponentScan("package")` | Not available |
| **Module discovery** | `@Configuration` - auto-discovered | Manual `@InstallIn` per module |
**Example comparison:**
```kotlin
// KOIN - That's it!
@Singleton
class MyRepository(val api: ApiService)
@Module
@ComponentScan("com.app")
class AppModule
```
```kotlin
// HILT - More ceremony
@Singleton
class MyRepository @Inject constructor(val api: ApiService)
@Module
@InstallIn(SingletonComponent::class)
abstract class AppModule {
@Binds
abstract fun bindRepository(impl: MyRepository): Repository
}
```
## Powered by Koin Compiler Plugin
The **Koin Compiler Plugin** is the recommended way to use Koin for all new projects:
- **Native Kotlin Compiler Plugin (K2)** - Not KSP, direct compiler integration
- **Auto-detects constructor parameters** - Less manual wiring
- **Compile-time safety** - Errors caught during build
- **Works with both DSL and Annotations** - Your choice
- **Simple setup** - One Gradle plugin
### Cleaner Syntax with Compiler Plugin
| Classic DSL | Compiler Plugin DSL |
|-------------|---------------------|
| `singleOf(::MyService)` | `single()` |
| `single { MyService(get(), get()) }` | `single()` |
| `factoryOf(::MyRepo)` | `factory()` |
| `viewModelOf(::MyVM)` | `viewModel()` |
Learn more in [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin).
## Classic DSL (Fully Supported)
The classic DSL remains fully supported for all Kotlin versions:
```kotlin
val appModule = module {
singleOf(::Database)
singleOf(::ApiClient)
singleOf(::UserRepository)
viewModelOf(::UserViewModel)
}
```
Or with explicit wiring:
```kotlin
val appModule = module {
single { Database() }
single { ApiClient() }
single { UserRepository(get(), get()) }
viewModel { UserViewModel(get()) }
}
```
:::info
Classic DSL is not deprecated. Koin works perfectly with it. The Compiler Plugin adds compile-time analysis on top when you're ready to migrate.
:::
## Koin Annotations is now part of the Koin project
The `koin-annotations` library โ `@Singleton`, `@Factory`, `@KoinViewModel`, `@Module`, `@ComponentScan`, and the rest โ ships under the main Koin version and is fully supported. It is **not** deprecated.
```kotlin
dependencies {
implementation(platform("io.insert-koin:koin-bom:$koin_version"))
implementation("io.insert-koin:koin-core")
implementation("io.insert-koin:koin-annotations") // same Koin version
}
```
Your annotations are processed by the **Koin Compiler Plugin** โ see [Koin Compiler Plugin](/docs/intro/koin-compiler-plugin) and the [Annotations Reference](/docs/reference/koin-annotations/start).
## Koin KSP Compiler is deprecated in favor of Koin Compiler Plugin
:::info
The legacy KSP processor `koin-ksp-compiler` is **deprecated** and will be removed in a future Koin version. The replacement is the **Koin Compiler Plugin** โ native K2 compiler integration, no generated files, simpler KMP setup.
:::
If you're using Koin Annotations with `koin-ksp-compiler`, migrate to the Compiler Plugin:
- **Same annotations** โ No code changes needed
- **Better processing** โ Native compiler integration, no generated files
- **Simpler setup** โ No KSP configuration
See [Migrating from KSP to Compiler Plugin](/docs/migration/from-ksp-to-compiler-plugin).
## Runtime + Compile Safe = Best of Both Worlds
Koin is **runtime-based but performant and compile-safe**. This unique combination enables:
**Compile-time safety** (with Compiler Plugin):
- Validates your dependency graph during build
- Auto-detects constructor parameters
- Catches missing dependencies before runtime
**Runtime flexibility** (that compile-time-only frameworks can't offer):
- Dynamic module loading/unloading
- Lazy module loading (background)
- Feature flag driven injection
- Plugin architectures
- A/B testing with different implementations
```kotlin
// Dynamic module loading - impossible with Hilt
if (featureEnabled) {
loadKoinModules(premiumFeatureModule)
}
// Later, if feature disabled
unloadKoinModules(premiumFeatureModule)
```
## Who is Koin For?
Koin is ideal for:
- **Teams who value productivity** - Less boilerplate, faster development
- **Android developers** wanting cleaner DI than Hilt/Dagger
- **Kotlin Multiplatform projects** - Android, iOS, Desktop, Web, Backend
- **Enterprise projects** that need to scale
- **Anyone who believes DI shouldn't be complicated**
## Next Steps
- **[What is Dependency Injection?](/docs/intro/what-is-dependency-injection)** - Learn DI fundamentals
- **[Koin Compiler Plugin](/docs/intro/koin-compiler-plugin)** - The recommended approach
- **[Setup Guide](/docs/setup/gradle)** - Add Koin to your project
- **[Tutorials](/docs/tutorials/your-first-app)** - Build your first app with Koin
---
### Migration From Ksp To Compiler Plugin (`docs/migration/from-ksp-to-compiler-plugin.md`)
---
title: Migrating Koin Annotations from KSP to Compiler Plugin
---
# Migrating Koin Annotations: KSP to Compiler Plugin
This guide helps you migrate your Koin Annotations project from KSP-based processing to the new Koin Compiler Plugin.
:::info Good News!
**Your annotations stay exactly the same.** Only the build configuration and Koin startup code change.
:::
## What's Different?
| Aspect | KSP Processing | Compiler Plugin |
|--------|----------------|-----------------|
| **Processing** | KSP (separate step) | K2 Compiler (integrated) |
| **Generated files** | Visible in `build/generated/ksp` | None - inline transformations |
| **Build speed** | Slower | Faster |
| **KMP setup** | Per-platform KSP configuration | Single plugin application |
| **Koin startup** | `modules(AppModule().module)` | `startKoin()` |
| **Future support** | Deprecated | Active development |
## Requirements
- **Kotlin 2.3.20+** (K2 compiler required)
- **Gradle 8.x+**
## Migration Steps
### Step 1: Update Kotlin Version
The Compiler Plugin requires Kotlin 2.3.20+:
```kotlin
// build.gradle.kts
plugins {
kotlin("jvm") version "2.3.20" // 2.3.20 minimum
}
```
### Step 2: Update Version Catalog
**Before (KSP):**
```toml
[versions]
koin = "4.0.0"
koin-ksp = "2.0.0" # Separate versioning for KSP annotations
ksp = "2.0.0-1.0.22"
[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin-ksp" }
koin-ksp-compiler = { module = "io.insert-koin:koin-ksp-compiler", version.ref = "koin-ksp" }
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
```
**After (Compiler Plugin):**
```toml
[versions]
koin = "4.2.0"
koin-plugin = "1.0.0"
[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
```
:::note
`koin-annotations` is now part of the main Koin project and uses the same version as `koin-core`.
:::
### Step 3: Update Build Configuration
**Before (KSP):**
```kotlin
// build.gradle.kts
plugins {
alias(libs.plugins.ksp)
}
dependencies {
implementation(libs.koin.core)
implementation(libs.koin.annotations) // KSP version (separate versioning)
ksp(libs.koin.ksp.compiler)
}
ksp {
arg("KOIN_CONFIG_CHECK", "true")
}
```
**After (Compiler Plugin):**
```kotlin
// build.gradle.kts
plugins {
alias(libs.plugins.koin.compiler)
}
dependencies {
implementation(libs.koin.core)
implementation(libs.koin.annotations) // Same version as koin-core
}
// Optional configuration
koinCompiler {
userLogs = true // Log component detection
}
```
### Step 4: Update Koin Startup
This is the main code change. The KSP approach uses generated `.module` extensions, while the Compiler Plugin uses `@KoinApplication` with typed APIs.
**Before (KSP):**
```kotlin
import org.koin.ksp.generated.* // Generated extensions
@Module
@ComponentScan("com.myapp")
class AppModule
fun main() {
startKoin {
modules(AppModule().module) // Generated .module extension
}
}
```
**After (Compiler Plugin):**
```kotlin
// No generated imports needed
@Module
@ComponentScan("com.myapp")
class AppModule
@KoinApplication(modules = [AppModule::class])
class MyApp
fun main() {
startKoin() // Typed API
}
```
#### Android Example
**Before (KSP):**
```kotlin
import org.koin.ksp.generated.*
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
androidContext(this@MyApplication)
modules(AppModule().module)
}
}
}
```
**After (Compiler Plugin):**
```kotlin
@KoinApplication(modules = [AppModule::class])
class MyApp
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
androidContext(this@MyApplication)
}
}
}
```
### Step 5: Clean Up
Remove KSP-generated files and rebuild:
```bash
rm -rf build/generated/ksp
./gradlew clean build
```
## Annotations Stay the Same
All your annotated classes remain unchanged:
```kotlin
// No changes needed!
@Singleton
class UserRepository(private val database: Database)
@Factory
class GetUserUseCase(private val repository: UserRepository)
@KoinViewModel
class UserViewModel(private val useCase: GetUserUseCase) : ViewModel()
@Module
@ComponentScan("com.myapp")
class AppModule
```
All annotations work identically. See **[Annotations Reference](/docs/reference/koin-annotations/definitions)** for the complete list.
### Import Change: `@KoinViewModel`
The `@KoinViewModel` annotation package has changed:
```kotlin
// Before (KSP)
import org.koin.android.annotation.KoinViewModel
// After (Compiler Plugin)
import org.koin.core.annotation.KoinViewModel
```
### Top-Level Function Definitions (New)
The Compiler Plugin supports annotations on top-level functions, discovered by `@ComponentScan`:
```kotlin
@Singleton
fun provideDatabase(): DatabaseService = PostgresDatabase()
@Factory
fun provideCache(db: DatabaseService): CacheService = RedisCache(db)
@Module
@ComponentScan("com.myapp")
class AppModule
```
Function return type determines the binding type. Function parameters are injected as dependencies.
## DSL Syntax Changes
If you use Koin DSL modules alongside annotations, the Compiler Plugin introduces a cleaner syntax:
| KSP / Classic Style | Compiler Plugin Style |
|---------------------|----------------------|
| `singleOf(::MyService)` | `single()` |
| `factoryOf(::MyRepo)` | `factory()` |
| `viewModelOf(::MyVM)` | `viewModel()` |
| `scopedOf(::MyScoped)` | `scoped()` |
| `workerOf(::MyWorker)` | `worker()` |
| `single { fn(get()) }` | `single { create(::fn) }` |
```kotlin
// Before
val myModule = module {
singleOf(::MyService)
factoryOf(::MyRepository)
viewModelOf(::MyViewModel)
}
// After
import org.koin.plugin.module.dsl.*
val myModule = module {
single()
factory()
viewModel()
}
// Function builders โ for external libraries (Room, Retrofit, etc.)
fun createDatabase(context: Context): AppDatabase =
Room.databaseBuilder(context, AppDatabase::class.java, "db").build()
val dbModule = module {
single { create(::createDatabase) }
}
```
:::note
The Compiler Plugin DSL is in package **`org.koin.plugin.module.dsl`**. Classic DSL remains in `org.koin.dsl`.
:::
## Cross-Module Discovery
Use `@Configuration` for automatic module discovery across Gradle modules:
```kotlin
// In feature module
@Module
@ComponentScan
@Configuration
class FeatureModule
// In app module - FeatureModule is auto-discovered
@KoinApplication
object MyApp
startKoin() // FeatureModule automatically included
```
## KMP Migration
The Compiler Plugin greatly simplifies KMP setup.
**Before (KSP) - Per-platform configuration:**
```kotlin
// shared/build.gradle.kts
plugins {
kotlin("multiplatform")
id("com.google.devtools.ksp")
}
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.insert-koin:koin-core:$koin_version")
implementation("io.insert-koin:koin-annotations:$koin_ksp_version") // Separate version
}
}
}
dependencies {
// KSP compiler required for each platform
add("kspAndroid", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
add("kspIosX64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
add("kspIosArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
add("kspIosSimulatorArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
}
```
**After (Compiler Plugin) - Single plugin:**
```kotlin
// shared/build.gradle.kts
plugins {
kotlin("multiplatform")
alias(libs.plugins.koin.compiler)
}
kotlin {
sourceSets {
commonMain.dependencies {
implementation(libs.koin.core)
implementation(libs.koin.annotations)
}
}
}
```
## Typed Startup APIs
The Compiler Plugin provides typed APIs: `startKoin()`, `koinApplication()`, `koinConfiguration()`.
See **[Starting with Annotations](/docs/reference/koin-annotations/start)** for details.
## Configuration Labels (New)
The Compiler Plugin adds configuration labels for conditional module loading.
See **[Modules - Configuration](/docs/reference/koin-annotations/modules)** for details.
## Compiler Plugin Options
See **[Compiler Plugin Options](/docs/reference/koin-annotations/options)** for all configuration options.
## Troubleshooting
### Build fails after removing KSP
1. `./gradlew clean`
2. `rm -rf build/generated/ksp`
3. Invalidate IDE caches
4. Rebuild
### Annotations not detected
Enable logging:
```kotlin
koinCompiler {
userLogs = true
}
```
### Missing dependencies at runtime
1. Check `@ComponentScan` packages
2. Verify modules in `@KoinApplication(modules = [...])`
3. Use `@Provided` for external dependencies
## Migration Checklist
- [ ] Update Kotlin to 2.3.20+
- [ ] Update Koin to 4.2.0+
- [ ] Remove KSP plugin
- [ ] Remove `koin-ksp-compiler` dependency
- [ ] Update `koin-annotations` to main Koin version (`io.insert-koin:koin-annotations:$koin_version`)
- [ ] Add Koin Compiler Plugin (`io.insert-koin.compiler.plugin`)
- [ ] Update `@KoinViewModel` import to `org.koin.core.annotation`
- [ ] Create `@KoinApplication` class and replace `modules(X().module)` with `startKoin()`
- [ ] Update DSL imports to `org.koin.plugin.module.dsl.*` if using DSL modules
- [ ] Update DSL syntax: `singleOf(::X)` โ `single()`
- [ ] Remove `import org.koin.ksp.generated.*`
- [ ] Clean and rebuild (`rm -rf build/generated/ksp && ./gradlew clean build`)
## See Also
- **[Compiler Plugin Setup](/docs/setup/compiler-plugin)** - Complete setup guide
- **[Annotations Reference](/docs/reference/koin-annotations/start)** - All annotations
- **[KSP Processor Setup (Deprecated)](/docs/setup/annotations-ksp)** โ Legacy `koin-ksp-compiler` reference
---
### Quickstart Android Annotations (`docs/quickstart/android-annotations.md`)
---
title: Android & Annotations
---
> This tutorial lets you write an Android application and use Koin dependency injection to retrieve your components.
> You need around __10 min__ to do the tutorial.
:::note
update - 2024-10-21
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/android-annotations)
:::
## Gradle Setup
Let's configure the KSP Plugin like this, and the following dependencies:
```groovy
plugins {
alias(libs.plugins.ksp)
}
dependencies {
// ...
implementation(libs.koin.annotations)
ksp(libs.koin.ksp)
}
// Compile time check
ksp {
arg("KOIN_CONFIG_CHECK","true")
}
```
:::note
See `libs.versions.toml` for current versions
:::
## Application Overview
The idea of the application is to manage a list of users, and display it in our `MainActivity` class with a Presenter or a ViewModel:
> Users -> UserRepository -> UserService -> (Presenter or ViewModel) -> MainActivity
## The "User" Data
We will manage a collection of Users. Here is the data class:
```kotlin
data class User(val name: String, val email: String)
```
We create a "Repository" component to manage the list of users (add users or find one by name). Here below, the `UserRepository` interface and its implementation:
```kotlin
interface UserRepository {
fun findUserOrNull(name: String): User?
fun addUsers(users: List)
}
@Singleton
class UserRepositoryImpl : UserRepository {
private val _users = arrayListOf()
override fun findUserOrNull(name: String): User? {
return _users.firstOrNull { it.name == name }
}
override fun addUsers(users: List) {
_users.addAll(users)
}
}
```
## The UserService Component
Let's write a service component to manage user operations:
```kotlin
interface UserService {
fun getUserOrNull(name: String): User?
fun loadUsers()
fun prepareHelloMessage(user: User?): String
}
@Singleton
class UserServiceImpl(
private val userRepository: UserRepository
) : UserService {
init {
loadUsers()
}
override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)
override fun loadUsers() {
userRepository.addUsers(listOf(
User("Alice", "alice@example.com"),
User("Bob", "bob@example.com"),
User("Charlie", "charlie@example.com")
))
}
override fun prepareHelloMessage(user: User?): String {
return user?.let { "Hello '${user.name}' (${user.email})! ๐" } ?: "โ User not found"
}
}
```
## The Koin module
Let's declare a `AppModule` module class like below:
```kotlin
@Module
@ComponentScan("org.koin.sample")
@Configuration
class AppModule
```
* `@Module` - Declares this class as a Koin module
* `@ComponentScan("org.koin.sample")` - Automatically scans and registers all Koin definitions in the `"org.koin.sample"` package
* `@Configuration` - Enables automatic module discovery when used with `@KoinApplication`
With component scanning enabled, we simply add annotations to our classes:
```kotlin
@Singleton
class UserRepositoryImpl : UserRepository {
// ...
}
@Singleton
class UserServiceImpl(private val userRepository: UserRepository) : UserService {
// ...
}
```
The `@Singleton` annotation declares these classes as singletons in Koin.
## Displaying User with Presenter
Let's write a presenter component to display a user:
```kotlin
@Factory
class UserPresenter(private val userService: UserService) {
fun sayHello(name: String): String {
val user = userService.getUserOrNull(name)
val message = userService.prepareHelloMessage(user)
return "[UserPresenter] $message"
}
}
```
> UserService is referenced in UserPresenter's constructor
We declare `UserPresenter` with the `@Factory` annotation, to create a new instance each time it's requested (avoids memory leaks with Android lifecycle):
```kotlin
@Factory
class UserPresenter(private val userService: UserService) {
// ...
}
```
## Injecting Dependencies in Android
The `UserPresenter` component will be created, resolving the `UserService` instance with it. To get it into our Activity, let's inject it with the `by inject()` delegate function:
```kotlin
class MainActivity : AppCompatActivity() {
private val presenter: UserPresenter by inject()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//...
}
}
```
That's it, your app is ready.
:::info
The `by inject()` function allows us to retrieve Koin instances, in Android components runtime (Activity, fragment, Service...)
:::
## Start Koin
We need to start Koin with our Android application. With the `@KoinApplication` annotation, Koin automatically discovers and loads all modules marked with `@Configuration`:
```kotlin
import org.koin.android.ext.koin.androidContext
import org.koin.core.annotation.KoinApplication
import org.koin.ksp.generated.*
@KoinApplication
class MainApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
androidContext(this@MainApplication)
}
}
}
```
**Key Points:**
* `@KoinApplication` - Automatically discovers all modules annotated with `@Module` and `@Configuration`
* No need to manually call `modules(AppModule().module)` - modules are loaded automatically!
* The `import org.koin.ksp.generated.*` import is required for generated Koin content
* You only need to configure Android-specific settings like `androidContext`
:::info
The `@KoinApplication` annotation works with `@Configuration` on your module to automatically discover and load all dependencies at compile time via KSP.
:::
## Displaying User with ViewModel
Let's write a ViewModel component to display a user:
```kotlin
@KoinViewModel
class UserViewModel(private val userService: UserService) : ViewModel() {
fun sayHello(name: String): String {
val user = userService.getUserOrNull(name)
val message = userService.prepareHelloMessage(user)
return "[UserViewModel] $message"
}
}
```
> UserService is referenced in UserViewModel's constructor
The `UserViewModel` is tagged with `@KoinViewModel` annotation to declare the Koin ViewModel definition. This ensures proper lifecycle management and avoids memory leaks.
## Injecting ViewModel in Android
The `UserViewModel` component will be created, resolving the `UserService` instance with it. To get it into our Activity, let's inject it with the `by viewModel()` delegate function:
```kotlin
class MainActivity : AppCompatActivity() {
private val viewModel: UserViewModel by viewModel()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//...
}
}
```
## Compile Time Checks
Koin Annotations allows to check your Koin configuration at compile time. This is available by using the following Gradle option:
```groovy
ksp {
arg("KOIN_CONFIG_CHECK","true")
}
```
:::tip
This KSP-based option has been replaced by the **Koin Compiler Plugin** which provides native compile-time safety. See [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety) and [Compiler Plugin Setup](/docs/setup/compiler-plugin).
:::
---
### Quickstart Android Compose (`docs/quickstart/android-compose.md`)
---
title: Android - Jetpack Compose
---
> This tutorial lets you write an Android application with Jetpack Compose UI and use Koin dependency injection to retrieve your components.
> You need around __10 min__ to do the tutorial.
:::note
update - 2024-11-28
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/android-compose)
:::
## Gradle Setup
Add the Koin Android and Koin Compose dependencies like below:
```groovy
dependencies {
// Koin for Android
implementation("io.insert-koin:koin-android:$koin_version")
// Koin for Jetpack Compose
implementation("io.insert-koin:koin-androidx-compose:$koin_version")
}
```
## Application Overview
The idea of the application is to manage a list of users, and display it in our `MainActivity` class with a ViewModel and Jetpack Compose UI:
> Users -> UserRepository -> UserService -> UserViewModel -> MainActivity (Compose UI)
## The "User" Data
We will manage a collection of Users. Here is the data class:
```kotlin
data class User(val name: String, val email: String)
```
We create a "Repository" component to manage the list of users (add users or find one by name). Here below, the `UserRepository` interface and its implementation:
```kotlin
interface UserRepository {
fun findUserOrNull(name: String): User?
fun addUsers(users: List)
}
class UserRepositoryImpl : UserRepository {
private val _users = arrayListOf()
override fun findUserOrNull(name: String): User? {
return _users.firstOrNull { it.name == name }
}
override fun addUsers(users: List) {
_users.addAll(users)
}
}
```
## The UserService Component
Let's write a service component to manage user operations:
```kotlin
interface UserService {
fun getUserOrNull(name: String): User?
fun loadUsers()
fun prepareHelloMessage(user: User?): String
}
class UserServiceImpl(
private val userRepository: UserRepository
) : UserService {
override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)
override fun loadUsers() {
userRepository.addUsers(listOf(
User("Alice", "alice@example.com"),
User("Bob", "bob@example.com"),
User("Charlie", "charlie@example.com")
))
}
override fun prepareHelloMessage(user: User?): String {
return user?.let { "Hello '${user.name}' (${user.email})! ๐" } ?: "โ User not found"
}
}
```
## The Koin module
Use the `module` function to declare a Koin module. A Koin module is the place where we define all our components to be injected.
```kotlin
val appModule = module {
}
```
Let's declare our components. We want singletons of `UserRepository` and `UserService`:
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
}
```
:::info
This tutorial uses the **Koin Compiler Plugin DSL** (`single()`, `viewModel()`) which provides auto-wiring at compile time. See [Compiler Plugin Setup](/docs/setup/compiler-plugin) for configuration.
:::
## Displaying User with ViewModel
Let's write a ViewModel component to display a user:
```kotlin
class UserViewModel(private val userService: UserService) : ViewModel() {
fun sayHello(name: String): String {
val user = userService.getUserOrNull(name)
val message = userService.prepareHelloMessage(user)
return "[UserViewModel] $message"
}
}
```
> UserService is referenced in UserViewModel's constructor
We declare `UserViewModel` in our Koin module. We declare it as a `viewModel` definition, to not keep any instance in memory (avoid any leak with Android lifecycle):
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
viewModel()
}
```
## Injecting ViewModel in Jetpack Compose
With Jetpack Compose, we use `ComponentActivity` instead of `AppCompatActivity`, and we build our UI with composable functions instead of XML layouts.
The `UserViewModel` component will be created, resolving the `UserService` instance with it. To get it into our Compose UI, we use the `koinViewModel()` function:
```
/* Detailed source-code truncated for AI context efficiency. */
```
That's it, your Compose app is ready!
:::info
The `koinViewModel()` function retrieves a ViewModel instance from Koin and automatically binds it to the Compose lifecycle. This is the Compose-specific way to inject ViewModels, replacing the `by viewModel()` delegate used in traditional Android Views.
:::
### Key Compose Concepts
- **ComponentActivity**: Base class for Compose apps (instead of AppCompatActivity)
- **setContent**: Sets the Composable content as the activity's UI
- **@Composable**: Functions that build UI declaratively
- **remember & mutableStateOf**: Compose state management for reactive UI updates
- **koinViewModel()**: Koin's Compose integration for ViewModel injection
## Start Koin
We need to start Koin with our Android application. Just call the `startKoin()` function in the application's main entry point, our `MainApplication` class:
```kotlin
class MainApplication : Application(){
override fun onCreate() {
super.onCreate()
startKoin{
androidLogger()
androidContext(this@MainApplication)
modules(appModule)
}
}
}
```
:::info
The `modules()` function in `startKoin` load the given list of modules
:::
## Koin module: DSL comparison
Here is the Koin module declaration using **Classic DSL** (manual wiring):
```kotlin
val appModule = module {
single { UserRepositoryImpl() }
single { UserServiceImpl(get()) }
viewModel { UserViewModel(get()) }
}
```
With **Compiler Plugin DSL** (auto-wiring at compile time):
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
viewModel()
}
```
:::tip
The Compiler Plugin DSL requires the [Koin Compiler Plugin](/docs/setup/compiler-plugin). It provides compile-time dependency resolution and cleaner syntax.
:::
## Compose vs XML Views
This tutorial demonstrates the same functionality as the [Android ViewModel tutorial](./android-viewmodel.md), but using Jetpack Compose instead of XML layouts:
| Aspect | XML Views | Jetpack Compose |
|--------|-----------|-----------------|
| Activity Base | `AppCompatActivity` | `ComponentActivity` |
| UI Definition | XML layout files | `@Composable` functions |
| ViewModel Injection | `by viewModel()` delegate | `koinViewModel()` function |
| State Management | LiveData/StateFlow | `remember` + `mutableStateOf` |
| UI Updates | View binding + observers | Automatic recomposition |
:::tip
For a version using Koin Annotations with Compose, see the [Compose Multiplatform Annotations tutorial](./compose-multiplatform-annotations.md).
:::
---
### Quickstart Android Viewmodel (`docs/quickstart/android-viewmodel.md`)
---
title: Android - ViewModel
---
> This tutorial lets you write an Android application and use Koin dependency injection to retrieve your components.
> You need around __10 min__ to do the tutorial.
:::note
update - 2024-10-21
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/android)
:::
## Gradle Setup
Add the Koin Android dependency like below:
```groovy
dependencies {
// Koin for Android
implementation("io.insert-koin:koin-android:$koin_version")
}
```
## Application Overview
The idea of the application is to manage a list of users, and display it in our `MainActivity` class with a Presenter or a ViewModel:
> Users -> UserRepository -> UserService -> (Presenter or ViewModel) -> MainActivity
## The "User" Data
We will manage a collection of Users. Here is the data class:
```kotlin
data class User(val name: String, val email: String)
```
We create a "Repository" component to manage the list of users (add users or find one by name). Here below, the `UserRepository` interface and its implementation:
```kotlin
interface UserRepository {
fun findUserOrNull(name: String): User?
fun addUsers(users: List)
}
class UserRepositoryImpl : UserRepository {
private val _users = arrayListOf()
override fun findUserOrNull(name: String): User? {
return _users.firstOrNull { it.name == name }
}
override fun addUsers(users: List) {
_users.addAll(users)
}
}
```
## The UserService Component
Let's write a service component to manage user operations:
```kotlin
interface UserService {
fun getUserOrNull(name: String): User?
fun loadUsers()
fun prepareHelloMessage(user: User?): String
}
class UserServiceImpl(
private val userRepository: UserRepository
) : UserService {
override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)
override fun loadUsers() {
userRepository.addUsers(listOf(
User("Alice", "alice@example.com"),
User("Bob", "bob@example.com"),
User("Charlie", "charlie@example.com")
))
}
override fun prepareHelloMessage(user: User?): String {
return user?.let { "Hello '${user.name}' (${user.email})! ๐" } ?: "โ User not found"
}
}
```
## The Koin module
Use the `module` function to declare a Koin module. A Koin module is the place where we define all our components to be injected.
```kotlin
val appModule = module {
}
```
Let's declare our components. We want singletons of `UserRepository` and `UserService`:
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
}
```
:::info
This tutorial uses the **Koin Compiler Plugin DSL** (`single()`, `viewModel()`) which provides auto-wiring at compile time. See [Compiler Plugin Setup](/docs/setup/compiler-plugin) for configuration.
:::
## Displaying User with ViewModel
Let's write a ViewModel component to display a user:
```kotlin
class UserViewModel(private val userService: UserService) : ViewModel() {
fun sayHello(name: String): String {
val user = userService.getUserOrNull(name)
val message = userService.prepareHelloMessage(user)
return "[UserViewModel] $message"
}
}
```
> UserService is referenced in UserViewModel's constructor
We declare `UserViewModel` in our Koin module. We declare it as a `viewModel` definition, to not keep any instance in memory (avoid any leak with Android lifecycle):
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
viewModel()
}
```
## Injecting ViewModel in Android
The `UserViewModel` component will be created, resolving the `UserService` instance with it. To get it into our Activity, let's inject it with the `by viewModel()` delegate function:
```kotlin
class MainActivity : AppCompatActivity() {
private val viewModel: UserViewModel by viewModel()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//...
}
}
```
That's it, your app is ready.
:::info
The `by viewModel()` function allows us to retrieve a ViewModel instances, create the associated ViewModel Factory for you and bind it to the lifecycle
:::
## Start Koin
We need to start Koin with our Android application. Just call the `startKoin()` function in the application's main entry point, our `MainApplication` class:
```kotlin
class MainApplication : Application(){
override fun onCreate() {
super.onCreate()
startKoin{
androidLogger()
androidContext(this@MainApplication)
modules(appModule)
}
}
}
```
:::info
The `modules()` function in `startKoin` load the given list of modules
:::
## Koin module: DSL comparison
Here is the Koin module declaration using **Classic DSL** (manual wiring):
```kotlin
val appModule = module {
single { UserRepositoryImpl() }
single { UserServiceImpl(get()) }
viewModel { UserViewModel(get()) }
}
```
With **Compiler Plugin DSL** (auto-wiring at compile time):
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
viewModel()
}
```
:::tip
The Compiler Plugin DSL requires the [Koin Compiler Plugin](/docs/setup/compiler-plugin). It provides compile-time dependency resolution and cleaner syntax.
:::
---
### Quickstart Android (`docs/quickstart/android.md`)
---
title: Android
---
> This tutorial lets you write an Android application and use Koin dependency injection to retrieve your components.
> You need around __10 min__ to do the tutorial.
:::note
update - 2024-10-21
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/android)
:::
## Gradle Setup
Add the Koin Android dependency like below:
```groovy
dependencies {
// Koin for Android
implementation("io.insert-koin:koin-android:$koin_version")
}
```
## Application Overview
The idea of the application is to manage a list of users, and display it in our `MainActivity` class with a Presenter or a ViewModel:
> Users -> UserRepository -> UserService -> (Presenter or ViewModel) -> MainActivity
## The "User" Data
We will manage a collection of Users. Here is the data class:
```kotlin
data class User(val name: String, val email: String)
```
We create a "Repository" component to manage the list of users (add users or find one by name). Here below, the `UserRepository` interface and its implementation:
```kotlin
interface UserRepository {
fun findUserOrNull(name: String): User?
fun addUsers(users: List)
}
class UserRepositoryImpl : UserRepository {
private val _users = arrayListOf()
override fun findUserOrNull(name: String): User? {
return _users.firstOrNull { it.name == name }
}
override fun addUsers(users: List) {
_users.addAll(users)
}
}
```
## The UserService Component
Let's write a service component to manage user operations:
```kotlin
interface UserService {
fun getUserOrNull(name: String): User?
fun loadUsers()
fun prepareHelloMessage(user: User?): String
}
class UserServiceImpl(
private val userRepository: UserRepository
) : UserService {
override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)
override fun loadUsers() {
userRepository.addUsers(listOf(
User("Alice", "alice@example.com"),
User("Bob", "bob@example.com"),
User("Charlie", "charlie@example.com")
))
}
override fun prepareHelloMessage(user: User?): String {
return user?.let { "Hello '${user.name}' (${user.email})! ๐" } ?: "โ User not found"
}
}
```
## The Koin module
Use the `module` function to declare a Koin module. A Koin module is the place where we define all our components to be injected.
```kotlin
val appModule = module {
}
```
Let's declare our components. We want singletons of `UserRepository` and `UserService`:
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
}
```
:::info
This tutorial uses the **Koin Compiler Plugin DSL** (`single()`, `factory()`) which provides auto-wiring at compile time. See [Compiler Plugin Setup](/docs/setup/compiler-plugin) for configuration.
:::
## Displaying User with Presenter
Let's write a presenter component to display a user:
```kotlin
class UserPresenter(private val userService: UserService) {
fun sayHello(name: String): String {
val user = userService.getUserOrNull(name)
val message = userService.prepareHelloMessage(user)
return "[UserPresenter] $message"
}
}
```
> UserService is referenced in UserPresenter's constructor
We declare `UserPresenter` in our Koin module. We declare it as a `factory` definition, to not keep any instance in memory (avoid any leak with Android lifecycle):
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
factory()
}
```
## Injecting Dependencies in Android
The `UserPresenter` component will be created, resolving the `UserService` instance with it. To get it into our Activity, let's inject it with the `by inject()` delegate function:
```kotlin
class MainActivity : AppCompatActivity() {
private val presenter: UserPresenter by inject()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//...
}
}
```
That's it, your app is ready.
:::info
The `by inject()` function allows us to retrieve Koin instances, in Android components runtime (Activity, fragment, Service...)
:::
## Start Koin
We need to start Koin with our Android application. Just call the `startKoin()` function in the application's main entry point, our `MainApplication` class:
```kotlin
class MainApplication : Application(){
override fun onCreate() {
super.onCreate()
startKoin{
androidLogger()
androidContext(this@MainApplication)
modules(appModule)
}
}
}
```
:::info
The `modules()` function in `startKoin` load the given list of modules
:::
## Koin module: DSL comparison
Here is the Koin module declaration using **Classic DSL** (manual wiring):
```kotlin
val appModule = module {
single { UserRepositoryImpl() }
single { UserServiceImpl(get()) }
factory { UserPresenter(get()) }
}
```
With **Compiler Plugin DSL** (auto-wiring at compile time):
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
factory()
}
```
:::tip
The Compiler Plugin DSL requires the [Koin Compiler Plugin](/docs/setup/compiler-plugin). It provides compile-time dependency resolution and cleaner syntax.
:::
---
### Quickstart Cmp (`docs/quickstart/cmp.md`)
---
title: Compose Multiplatform - Shared UI
---
> This tutorial demonstrates a Compose Multiplatform application that displays museum art from The Metropolitan Museum of Art Collection API. It uses Koin for dependency injection across Android and iOS platforms with shared UI.
> You need around __20 min__ to complete the tutorial.
:::note
update - 2024-11-12
:::
:::tip
Looking for the **annotations version** of this tutorial? Check out [Compose Multiplatform & Annotations](./compose-multiplatform-annotations.md) which uses Koin Annotations for compile-time verification and automatic module discovery.
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/compose)
:::
## Application Overview
The application fetches museum art objects from a remote API and displays them in a list. Users can tap on an item to see detailed information:
`MuseumAPI -> MuseumStorage -> MuseumRepository -> ViewModels -> Compose UI`
**Technologies used:**
- Compose Multiplatform for shared UI (Android & iOS)
- Ktor for HTTP networking
- Koin for dependency injection
- Kotlin Coroutines & Flow for async operations
- Navigation Compose for routing
## The Data Layer
> All the common/shared code is located in `composeApp` Gradle project
### MuseumObject Model
The museum art object data class:
```kotlin
@Serializable
data class MuseumObject(
val objectID: Int,
val title: String,
val artistDisplayName: String,
val medium: String,
val dimensions: String,
val objectURL: String,
val objectDate: String,
val primaryImage: String,
val primaryImageSmall: String,
val repository: String,
val department: String,
val creditLine: String,
)
```
### MuseumApi - Network Layer
We create an API interface to fetch data from The Metropolitan Museum of Art API:
```kotlin
interface MuseumApi {
suspend fun getData(): List
}
class KtorMuseumApi(private val client: HttpClient) : MuseumApi {
private companion object {
const val API_URL = "https://raw.githubusercontent.com/Kotlin/KMP-App-Template/main/list.json"
}
override suspend fun getData(): List {
return try {
client.get(API_URL).body()
} catch (e: Exception) {
if (e is CancellationException) throw e
e.printStackTrace()
emptyList()
}
}
}
```
### MuseumStorage - Local Caching
We create a storage interface to cache museum objects locally:
```kotlin
interface MuseumStorage {
suspend fun saveObjects(newObjects: List)
fun getObjectById(objectId: Int): Flow
fun getObjects(): Flow>
}
class InMemoryMuseumStorage : MuseumStorage {
private val storedObjects = MutableStateFlow(emptyList())
override suspend fun saveObjects(newObjects: List) {
storedObjects.value = newObjects
}
override fun getObjectById(objectId: Int): Flow {
return storedObjects.map { objects ->
objects.find { it.objectID == objectId }
}
}
override fun getObjects(): Flow> = storedObjects
}
```
### MuseumRepository
The repository coordinates between the API and storage:
```kotlin
class MuseumRepository(
private val museumApi: MuseumApi,
private val museumStorage: MuseumStorage,
) {
private val scope = CoroutineScope(SupervisorJob())
init {
initialize()
}
fun initialize() {
scope.launch {
refresh()
}
}
suspend fun refresh() {
museumStorage.saveObjects(museumApi.getData())
}
fun getObjects(): Flow> = museumStorage.getObjects()
fun getObjectById(objectId: Int): Flow = museumStorage.getObjectById(objectId)
}
```
## The Shared Koin Modules
Use the `module` function to declare Koin modules. We organize our dependencies into separate modules for better structure.
:::info
This tutorial uses the **Koin Compiler Plugin DSL** (`single()`, `viewModel()`) which provides auto-wiring at compile time. See [Compiler Plugin Setup](/docs/setup/compiler-plugin) for configuration.
:::
### Data Module
```kotlin
val dataModule = module {
// HttpClient for Ktor
single { create(::buildClient) }
// API, Storage, and Repository
single() bind MuseumApi::class
single() bind MuseumStorage::class
single() withOptions { createdAtStart() }
}
private fun buildClient(): HttpClient {
val json = Json { ignoreUnknownKeys = true }
return HttpClient {
install(ContentNegotiation) {
json(json, contentType = ContentType.Any)
}
}
}
```
### ViewModel Module
Let's create ViewModels for our two screens:
```kotlin
// List screen ViewModel
class ListViewModel(museumRepository: MuseumRepository) : ViewModel() {
val objects: StateFlow> =
museumRepository.getObjects()
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
}
// Detail screen ViewModel
class DetailViewModel(private val museumRepository: MuseumRepository) : ViewModel() {
fun getObject(objectId: Int): StateFlow {
return museumRepository.getObjectById(objectId)
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), null)
}
}
```
Declare them in the ViewModel module:
```kotlin
val viewModelModule = module {
viewModel()
viewModel()
}
```
### Platform-Specific Module
For platform-specific components (Android vs iOS):
```kotlin
val nativeComponentModule = module {
single()
}
```
### Main App Module
Combine all modules:
```kotlin
val appModule = module {
includes(dataModule, viewModelModule, nativeComponentModule)
}
```
:::note
The Koin modules are organized and can be initialized from both Android and iOS using the `initKoin()` function.
:::
## Native Component
For platform-specific information (Android vs iOS), we use an expect/actual pattern:
```kotlin
// commonMain
interface NativeComponent {
fun getInfo(): String
}
// androidMain
class NativeComponent {
fun getInfo(): String = "Android ${android.os.Build.VERSION.SDK_INT}"
}
// iosMain
class NativeComponent {
fun getInfo(): String = "iOS ${UIDevice.currentDevice.systemVersion}"
}
```
## Injecting ViewModels in Compose
> All the common Compose app is located in `commonMain` from `composeApp` Gradle module
The ViewModels are injected using `koinViewModel()` in Compose:
```kotlin
@Composable
fun App() {
MaterialTheme(
colorScheme = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()
) {
Surface {
val navController: NavHostController = rememberNavController()
NavHost(navController = navController, startDestination = ListDestination) {
composable {
val vm = koinViewModel()
ListScreen(viewModel = vm, navigateToDetails = { objectId ->
navController.navigate(DetailDestination(objectId))
})
}
composable { backStackEntry ->
val vm = koinViewModel()
DetailScreen(
objectId = backStackEntry.toRoute().objectId,
viewModel = vm,
navigateBack = { navController.popBackStack() }
)
}
}
}
}
}
```
:::info
The `koinViewModel()` function retrieves ViewModel instances and binds them to the Compose lifecycle.
:::
## Starting Koin
Initialize Koin with the `initKoin()` function:
```kotlin
fun initKoin(configuration: KoinAppDeclaration? = null) {
startKoin {
includes(configuration)
modules(appModule)
}
val platformInfo = KoinPlatform.getKoin().get().getInfo()
println("Running on: $platformInfo")
}
```
### Android Setup
In Android, Koin is initialized from the main Activity or Application class:
```kotlin
// Call from Android entry point
initKoin()
```
### iOS Setup
> All the iOS app is located in `iosApp` folder
In iOS, initialize Koin from the SwiftUI App entry point:
```swift
@main
struct iOSApp: App {
init() {
KoinKt.doInitKoin()
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
```
The Compose UI is started with:
```kotlin
fun MainViewController() = ComposeUIViewController { App() }
```
---
### Quickstart Compose Multiplatform Annotations (`docs/quickstart/compose-multiplatform-annotations.md`)
---
title: Compose Multiplatform & Annotations - Shared UI
---
> This tutorial demonstrates a Compose Multiplatform application that displays museum art from The Metropolitan Museum of Art Collection API. It uses Koin Annotations for dependency injection across Android and iOS platforms with shared UI.
> You need around __20 min__ to complete the tutorial.
:::note
update - 2024-11-12
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/compose-annotations)
:::
## Gradle Setup
First, add the Koin annotations dependencies:
```kotlin
plugins {
id("com.google.devtools.ksp") version kspVersion
}
dependencies {
// Koin for Compose Multiplatform
implementation("io.insert-koin:koin-core:$koin_version")
implementation("io.insert-koin:koin-compose-viewmodel:$koin_version")
// Koin Annotations
implementation("io.insert-koin:koin-annotations:$koin_annotations_version")
ksp("io.insert-koin:koin-ksp-compiler:$koin_annotations_version")
}
```
## Application Overview
The application fetches museum art objects from a remote API and displays them in a list. Users can tap on an item to see detailed information:
`MuseumAPI -> MuseumStorage -> MuseumRepository -> ViewModels -> Compose UI`
**Technologies used:**
- Compose Multiplatform for shared UI (Android & iOS)
- Ktor for HTTP networking
- Koin Annotations for dependency injection
- Kotlin Coroutines & Flow for async operations
- Navigation Compose for routing
## The Data Layer
> All the common/shared code is located in `composeApp` Gradle project
### MuseumObject Model
The museum art object data class:
```kotlin
@Serializable
data class MuseumObject(
val objectID: Int,
val title: String,
val artistDisplayName: String,
val medium: String,
val dimensions: String,
val objectURL: String,
val objectDate: String,
val primaryImage: String,
val primaryImageSmall: String,
val repository: String,
val department: String,
val creditLine: String,
)
```
### MuseumApi - Network Layer
We create an API interface to fetch data:
```kotlin
interface MuseumApi {
suspend fun getData(): List
}
@Single
class KtorMuseumApi(private val client: HttpClient) : MuseumApi {
override suspend fun getData(): List {
return try {
client.get(API_URL).body()
} catch (e: Exception) {
if (e is CancellationException) throw e
e.printStackTrace()
emptyList()
}
}
}
```
### MuseumStorage - Local Caching
```kotlin
interface MuseumStorage {
suspend fun saveObjects(newObjects: List)
fun getObjectById(objectId: Int): Flow
fun getObjects(): Flow>
}
@Single
class InMemoryMuseumStorage : MuseumStorage {
private val storedObjects = MutableStateFlow(emptyList())
override suspend fun saveObjects(newObjects: List) {
storedObjects.value = newObjects
}
override fun getObjectById(objectId: Int): Flow {
return storedObjects.map { objects ->
objects.find { it.objectID == objectId }
}
}
override fun getObjects(): Flow> = storedObjects
}
```
### MuseumRepository
The repository coordinates between the API and storage:
```kotlin
@Single(createdAtStart = true)
class MuseumRepository(
private val museumApi: MuseumApi,
private val museumStorage: MuseumStorage,
) {
private val scope = CoroutineScope(SupervisorJob())
init {
initialize()
}
fun initialize() {
scope.launch {
refresh()
}
}
suspend fun refresh() {
museumStorage.saveObjects(museumApi.getData())
}
fun getObjects(): Flow> = museumStorage.getObjects()
fun getObjectById(objectId: Int): Flow = museumStorage.getObjectById(objectId)
}
```
:::note
The `@Single(createdAtStart = true)` annotation ensures the repository is created when Koin starts, triggering the data fetch immediately.
:::
## The Koin Modules
We organize our dependencies into separate modules:
### Data Module
```kotlin
@Module
@ComponentScan
class DataModule {
@Single
fun providesHttpClient(): HttpClient {
val json = Json { ignoreUnknownKeys = true }
return HttpClient {
install(ContentNegotiation) {
json(json, contentType = ContentType.Any)
}
}
}
}
```
The `@ComponentScan` annotation automatically discovers all `@Single` annotated classes in this package (MuseumApi, MuseumStorage, MuseumRepository).
### ViewModel Module
Let's create ViewModels for our two screens:
```kotlin
// List screen ViewModel
@KoinViewModel
class ListViewModel(museumRepository: MuseumRepository) : ViewModel() {
val objects: StateFlow> =
museumRepository.getObjects()
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), emptyList())
}
// Detail screen ViewModel
@KoinViewModel
class DetailViewModel(private val museumRepository: MuseumRepository) : ViewModel() {
fun getObject(objectId: Int): StateFlow {
return museumRepository.getObjectById(objectId)
.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), null)
}
}
```
Declare them in a module:
```kotlin
@ComponentScan
@Module
class ViewModelModule
```
The `@KoinViewModel` annotation automatically registers these as ViewModel definitions, and `@ComponentScan` discovers them.
### Platform-Specific Module
For platform-specific components (Android vs iOS):
```kotlin
@ComponentScan
@Module
class PlatformComponentModule
```
### Main App Module
Combine all modules:
```kotlin
@Configuration
@Module(includes = [DataModule::class, ViewModelModule::class, PlatformComponentModule::class])
class AppModule
```
* `@Configuration` - Enables automatic module discovery with `@KoinApplication`
* `@Module(includes = [...])` - Declares which modules to include
## Koin Application Object
Create a `@KoinApplication` object:
```kotlin
@KoinApplication
object KoinApp
fun initKoin(configuration: KoinAppDeclaration? = null) {
KoinApp.startKoin {
includes(configuration)
}
val platformInfo = KoinPlatform.getKoin().get().getInfo()
println("Running on: $platformInfo")
}
```
The `@KoinApplication` annotation generates a `startKoin()` extension function that automatically loads all modules.
## Injecting ViewModels in Compose
> All the common Compose app is located in `commonMain` from `composeApp` Gradle module
The ViewModels are injected using `koinViewModel()` in Compose:
```kotlin
@Composable
fun App() {
MaterialTheme(
colorScheme = if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()
) {
Surface {
val navController: NavHostController = rememberNavController()
NavHost(navController = navController, startDestination = ListDestination) {
composable {
val vm = koinViewModel()
ListScreen(viewModel = vm, navigateToDetails = { objectId ->
navController.navigate(DetailDestination(objectId))
})
}
composable { backStackEntry ->
val vm = koinViewModel()
DetailScreen(
objectId = backStackEntry.toRoute().objectId,
viewModel = vm,
navigateBack = { navController.popBackStack() }
)
}
}
}
}
}
```
:::info
The `koinViewModel()` function retrieves ViewModel instances automatically registered via `@KoinViewModel`.
:::
## Starting Koin
### Android Setup
In Android, Koin is initialized from the main entry point:
```kotlin
// Call from Android entry point
initKoin()
```
### iOS Setup
> All the iOS app is located in `iosApp` folder
In iOS, initialize Koin from the SwiftUI App entry point:
```swift
@main
struct iOSApp: App {
init() {
KoinKt.doInitKoin()
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
```
The Compose UI is started with:
```kotlin
fun MainViewController() = ComposeUIViewController { App() }
```
## Annotations vs Compiler Plugin DSL
Here's how the annotations approach compares to the Compiler Plugin DSL:
**With Annotations (compose-annotations/):**
```kotlin
@Configuration
@Module(includes = [DataModule::class, ViewModelModule::class])
class AppModule
@Single
class MuseumRepository(api: MuseumApi, storage: MuseumStorage)
@KoinViewModel
class ListViewModel(repository: MuseumRepository) : ViewModel()
// Start Koin
KoinApp.startKoin()
```
**Compiler Plugin DSL (compose/):**
```kotlin
val appModule = module {
includes(dataModule, viewModelModule)
}
val dataModule = module {
single() withOptions { createdAtStart() }
}
val viewModelModule = module {
viewModel()
}
// Start Koin
startKoin { modules(appModule) }
```
Both approaches achieve the same result:
- **Annotations**: Compile-time verification via KSP, automatic module discovery
- **Compiler Plugin DSL**: Auto-wiring at compile time, cleaner `single()` syntax
---
### Quickstart Junit Test (`docs/quickstart/junit-test.md`)
---
title: JUnit Tests
---
> This tutorial lets you test a Kotlin application and use Koin inject and retrieve your components.
:::note
update - 2025-01-28
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/kotlin)
:::
## Gradle Setup
First, add the Koin dependency like below:
```groovy
dependencies {
// Koin testing tools
testImplementation "io.insert-koin:koin-test:$koin_version"
// Needed JUnit version
testImplementation "io.insert-koin:koin-test-junit4:$koin_version"
}
```
## Declared dependencies
We reuse the `koin-core` getting-started project, to use the koin module:
```kotlin
val appModule = module {
single()
single() bind UserRepository::class
single() bind UserService::class
}
```
## Verifying your Modules
:::tip
The Koin Compiler Plugin now provides compile-time dependency validation, catching missing dependencies at build time without writing test code. See [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety).
:::
If you're not using the compiler plugin, you can verify modules at runtime. The `verify()` function performs a dry-run check to ensure all dependencies can be resolved:
```kotlin
class ModuleVerificationTest : AutoCloseKoinTest() {
@Test
fun verifyModules() {
appModule.verify()
}
}
```
This test will fail if any dependency definitions are invalid or if any required dependencies are missing.
## Writing Tests with KoinTestRule
To write tests that inject dependencies, extend `KoinTest` and use `KoinTestRule`:
```kotlin
class UserAppTest : KoinTest {
val userService by inject()
val userRepository by inject()
@get:Rule
val koinTestRule = KoinTestRule.create {
printLogger()
modules(appModule)
}
@Test
fun `test user service`() {
// Load users via service
userService.loadUsers()
// Verify user can be found
val user = userService.getUserOrNull("Alice")
assertNotNull(user)
assertEquals("Alice", user?.name)
}
}
```
> We use the `KoinTestRule` to start/stop our Koin context for each test
## Mocking Dependencies
You can mock dependencies in your tests using `declareMock`. This replaces the real implementation with a mock:
```kotlin
class UserMockTest : KoinTest {
@get:Rule
val koinTestRule = KoinTestRule.create {
printLogger(Level.DEBUG)
modules(appModule)
}
@get:Rule
val mockProvider = MockProviderRule.create { clazz ->
Mockito.mock(clazz.java)
}
@Test
fun `mock test`() {
// Declare a mock for UserRepository
val repository = declareMock {
given(findUserOrNull(anyString())).willReturn(
User("Mock", "mock@example.com")
)
}
// Use the application with mocked repository
getKoin().get().sayHello("Mock")
// Verify the mock was called
Mockito.verify(repository, times(1)).findUserOrNull(anyString())
}
}
```
The `MockProviderRule` configures Mockito as the mocking framework, and `declareMock` replaces the real `UserRepository` with a mock that returns controlled data.
## Key Testing Concepts
| Concept | Description |
|---------|-------------|
| `KoinTest` | Interface to extend for Koin testing support |
| `AutoCloseKoinTest` | Auto-closes Koin after each test |
| `KoinTestRule` | JUnit rule to start/stop Koin context |
| `MockProviderRule` | Configures the mocking framework |
| `verify()` | Validates module configuration without running |
| `declareMock()` | Replaces a definition with a mock |
| `by inject()` | Lazily injects a dependency in tests |
## See Also
- **[Testing Reference](/docs/reference/koin-test/testing)** - Complete testing documentation
- **[Module Verification](/docs/reference/koin-test/verify)** - verify() and checkModules() details
---
### Quickstart Kotlin Annotations (`docs/quickstart/kotlin-annotations.md`)
---
title: Kotlin & Annotations
---
> This tutorial lets you write a Kotlin application and use Koin dependency injection with annotations to retrieve your components.
> You need around __10 min__ to do the tutorial.
:::note
update - 2024-11-12
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/kotlin-annotations)
:::
## Setup
First, check that the Koin annotations dependencies are added like below:
```groovy
plugins {
id("com.google.devtools.ksp") version kspVersion
}
dependencies {
// Koin for Kotlin apps
implementation("io.insert-koin:koin-core:$koin_version")
// Koin Annotations
implementation("io.insert-koin:koin-annotations:$koin_annotations_version")
ksp("io.insert-koin:koin-ksp-compiler:$koin_annotations_version")
}
```
## Application Overview
The idea of the application is to manage a list of users, and display it in our `UserApplication` class:
> Users -> UserRepository -> UserService -> UserApplication
## The "User" Data
We will manage a collection of Users. Here is the data class:
```kotlin
data class User(val name: String, val email: String)
```
We create a "Repository" component to manage the list of users (add users or find one by name). Here below, the `UserRepository` interface and its implementation:
```kotlin
interface UserRepository {
fun findUserOrNull(name: String): User?
fun addUsers(users: List)
}
@Singleton
class UserRepositoryImpl : UserRepository {
private val _users = arrayListOf()
override fun findUserOrNull(name: String): User? {
return _users.firstOrNull { it.name == name }
}
override fun addUsers(users: List) {
_users.addAll(users)
}
}
```
:::note
This project uses Koin's `@Singleton` annotation (from `org.koin.core.annotation`) to declare singleton components.
:::
## The Koin module
Use the `@Module` annotation to declare a Koin module:
```kotlin
@Module
@ComponentScan("org.koin.sample")
@Configuration
class AppModule
```
* `@Module` - Declares this as a Koin module
* `@ComponentScan("org.koin.sample")` - Scans and registers annotated classes from the package
* `@Configuration` - Enables automatic module discovery with `@KoinApplication`
Let's declare our components by adding the `@Singleton` annotation:
```kotlin
@Singleton
class UserRepositoryImpl : UserRepository {
// ...
}
```
## The UserService Component
Let's write the UserService component to manage user operations:
```kotlin
interface UserService {
fun getUserOrNull(name: String): User?
fun loadUsers()
fun prepareHelloMessage(user: User?): String
}
@Singleton
class UserServiceImpl(
private val userRepository: UserRepository
) : UserService {
override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)
override fun loadUsers() {
userRepository.addUsers(listOf(
User("Alice", "alice@example.com"),
User("Bob", "bob@example.com"),
User("Charlie", "charlie@example.com")
))
}
override fun prepareHelloMessage(user: User?): String {
return user?.let { "Hello '${user.name}' (${user.email})! ๐" } ?: "โ User not found"
}
}
```
> UserRepository is referenced in UserServiceImpl's constructor
We declare `UserService` with the `@Singleton` annotation.
## The UserApplication
The `UserApplication` class uses constructor injection to receive the `UserService`:
```kotlin
@Singleton
class UserApplication(
private val userService: UserService
) {
init {
userService.loadUsers()
}
fun sayHello(name: String) {
val user = userService.getUserOrNull(name)
val message = userService.prepareHelloMessage(user)
println(message)
}
}
```
:::info
Constructor injection is the preferred way to inject dependencies. Koin will automatically resolve and inject the `UserService` when creating `UserApplication`.
:::
## Koin Application Object
Create a `@KoinApplication` object to mark the entry point for Koin's annotation-based configuration:
```kotlin
@KoinApplication
object KoinUserApplication
```
The `@KoinApplication` annotation works with the KSP processor to generate a `startKoin()` extension function for this object.
## Start Koin
We need to start Koin with our application. Just call the generated `startKoin()` function in the application's main entry point:
```kotlin
fun main() {
KoinUserApplication.startKoin()
val userApplication = KoinPlatform.getKoin().get()
userApplication.sayHello("Alice")
}
```
**Key Points:**
* `KoinUserApplication.startKoin()` - Generated function that automatically discovers and loads all modules
* No need to manually call `modules()` - all annotated dependencies are discovered at compile time!
* We retrieve the `UserApplication` instance from Koin using `KoinPlatform.getKoin().get()`
:::info
The `@KoinApplication` annotation with `@Configuration` on the module automatically discovers and loads all annotated dependencies at compile time via KSP.
:::
## Annotations vs Compiler Plugin DSL
Here is how our annotations-based configuration compares to the Compiler Plugin DSL:
**With Annotations:**
```kotlin
@Module
@ComponentScan("org.koin.sample")
@Configuration
class AppModule
@Singleton
class UserApplication(private val userService: UserService)
@Singleton
class UserRepositoryImpl : UserRepository
@Singleton
class UserServiceImpl(private val userRepository: UserRepository) : UserService
```
**Compiler Plugin DSL (from kotlin.md):**
```kotlin
val appModule = module {
single()
single() bind UserRepository::class
single() bind UserService::class
}
```
Both approaches achieve the same result:
- **Annotations**: Compile-time verification via KSP, automatic module discovery
- **Compiler Plugin DSL**: Auto-wiring at compile time, cleaner `single()` syntax
---
### Quickstart Kotlin (`docs/quickstart/kotlin.md`)
---
title: Kotlin
---
> This tutorial lets you write a Kotlin application and use Koin dependency injection to retrieve your components.
> You need around __10 min__ to do the tutorial.
:::note
update - 2024-10-21
:::
:::tip
Looking for the **annotations version** of this tutorial? Check out [Kotlin & Annotations](./kotlin-annotations.md) which uses Koin Annotations for compile-time verification and automatic module discovery.
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/kotlin)
:::
## Setup
First, check that the `koin-core` dependency is added like below:
```groovy
dependencies {
// Koin for Kotlin apps
implementation "io.insert-koin:koin-core:$koin_version"
}
```
## Application Overview
The idea of the application is to manage a list of users, and display it in our `UserApplication` class:
> Users -> UserRepository -> UserService -> UserApplication
## The "User" Data
We will manage a collection of Users. Here is the data class:
```kotlin
data class User(val name: String, val email: String)
```
We create a "Repository" component to manage the list of users (add users or find one by name). Here below, the `UserRepository` interface and its implementation:
```kotlin
interface UserRepository {
fun findUserOrNull(name: String): User?
fun addUsers(users: List)
}
class UserRepositoryImpl : UserRepository {
private val _users = arrayListOf()
override fun findUserOrNull(name: String): User? {
return _users.firstOrNull { it.name == name }
}
override fun addUsers(users: List) {
_users.addAll(users)
}
}
```
## The Koin module
Use the `module` function to declare a Koin module. A Koin module is the place where we define all our components to be injected.
```kotlin
val appModule = module {
}
```
Let's declare our first component. We want a singleton of `UserRepository`, by creating an instance of `UserRepositoryImpl`
```kotlin
val appModule = module {
single() bind UserRepository::class
}
```
:::info
This tutorial uses the **Koin Compiler Plugin DSL** (`single()`) which provides auto-wiring at compile time. See [Compiler Plugin Setup](/docs/setup/compiler-plugin) for configuration.
:::
## The UserService Component
Let's write the UserService component to manage user operations:
```kotlin
interface UserService {
fun getUserOrNull(name: String): User?
fun loadUsers()
fun prepareHelloMessage(user: User?): String
}
class UserServiceImpl(
private val userRepository: UserRepository
) : UserService {
override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)
override fun loadUsers() {
userRepository.addUsers(listOf(
User("Alice", "alice@example.com"),
User("Bob", "bob@example.com"),
User("Charlie", "charlie@example.com")
))
}
override fun prepareHelloMessage(user: User?): String {
return user?.let { "Hello '${user.name}' (${user.email})! ๐" } ?: "โ User not found"
}
}
```
> UserRepository is referenced in UserServiceImpl's constructor
We declare `UserService` in our Koin module. We declare it as a `single` definition:
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
}
```
## Injecting Dependencies in UserApplication
The `UserApplication` class will help bootstrap instances out of Koin. It will resolve the `UserService` through constructor injection:
```kotlin
class UserApplication(
private val userService: UserService
) {
init {
userService.loadUsers()
}
// display our data
fun sayHello(name: String) {
val user = userService.getUserOrNull(name)
val message = userService.prepareHelloMessage(user)
println(message)
}
}
```
That's it, your app is ready.
:::info
Constructor injection is the preferred way to inject dependencies in Kotlin applications. Koin will automatically resolve and inject the `UserService` when creating `UserApplication`.
:::
## Start Koin
We need to start Koin with our application and add `UserApplication` to our module. Just call the `startKoin()` function in the application's main entry point, our `main` function:
```kotlin
val appModule = module {
single()
single() bind UserRepository::class
single() bind UserService::class
}
fun main() {
startKoin {
modules(appModule)
}
val userApplication = KoinPlatform.getKoin().get()
userApplication.sayHello("Alice")
}
```
:::info
The `modules()` function in `startKoin` loads the given list of modules. We retrieve the `UserApplication` instance from Koin using `KoinPlatform.getKoin().get()`.
:::
## Koin module: DSL comparison
Here is the Koin module declaration using **Classic DSL** (manual wiring):
```kotlin
val appModule = module {
single { UserApplication(get()) }
single { UserRepositoryImpl() }
single { UserServiceImpl(get()) }
}
```
With **Compiler Plugin DSL** (auto-wiring at compile time):
```kotlin
val appModule = module {
single()
single() bind UserRepository::class
single() bind UserService::class
}
```
:::tip
The Compiler Plugin DSL requires the [Koin Compiler Plugin](/docs/setup/compiler-plugin). It provides compile-time dependency resolution and cleaner syntax.
:::
---
### Quickstart Ktor Annotations (`docs/quickstart/ktor-annotations.md`)
---
title: Ktor & Annotations
---
> Ktor is a framework for building asynchronous servers and clients in connected systems using the powerful Kotlin programming language. We will use Ktor here, to build a simple web application.
Let's go ๐
:::note
update - 2024-10-21
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/ktor-annotations)
:::
## Gradle Setup
First, add the Koin dependency like below:
```kotlin
plugins {
id("com.google.devtools.ksp") version kspVersion
}
dependencies {
// Koin for Kotlin apps
implementation("io.insert-koin:koin-ktor:$koin_version")
implementation("io.insert-koin:koin-logger-slf4j:$koin_version")
implementation("io.insert-koin:koin-annotations:$koinAnnotationsVersion")
ksp("io.insert-koin:koin-ksp-compiler:$koinAnnotationsVersion")
}
```
## Application Overview
The idea of the application is to manage a list of users, and display it in our `UserApplication` class:
> Users -> UserRepository -> UserService -> UserApplication
## The "User" Data
We will manage a collection of Users. Here is the data class:
```kotlin
data class User(val name: String, val email: String)
```
We create a "Repository" component to manage the list of users (add users or find one by name). Here below, the `UserRepository` interface and its implementation:
```kotlin
interface UserRepository {
fun findUserOrNull(name: String): User?
fun addUsers(users: List)
}
@Singleton
class UserRepositoryImpl : UserRepository {
private val _users = arrayListOf()
override fun findUserOrNull(name: String): User? {
return _users.firstOrNull { it.name == name }
}
override fun addUsers(users: List) {
_users.addAll(users)
}
}
```
## The Koin module
Use the `@Module` annotation to declare a Koin module, from a given Kotlin class. A Koin module is the place where we define all our components to be injected.
```kotlin
@Module
@ComponentScan("org.koin.sample")
@Configuration
class AppModule
```
* `@Module` - Declares this as a Koin module
* `@ComponentScan("org.koin.sample")` - Scans and registers annotated classes from the package
* `@Configuration` - Enables automatic module discovery with `@KoinApplication`
:::note
This project uses Koin's `@Singleton` annotation (from `org.koin.core.annotation`) to declare singleton components.
:::
Let's declare our first component. We want a singleton of `UserRepository`, by creating an instance of `UserRepositoryImpl`. We tag it `@Singleton`:
```kotlin
@Singleton
class UserRepositoryImpl : UserRepository
```
## The UserService Component
Let's write the UserService component to manage user operations:
```kotlin
interface UserService {
fun getUserOrNull(name: String): User?
fun loadUsers()
fun prepareHelloMessage(user: User?): String
}
@Singleton
class UserServiceImpl(
private val userRepository: UserRepository
) : UserService {
override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)
override fun loadUsers() {
userRepository.addUsers(listOf(
User("Alice", "alice@example.com"),
User("Bob", "bob@example.com"),
User("Charlie", "charlie@example.com")
))
}
override fun prepareHelloMessage(user: User?): String {
return user?.let { "Hello '${user.name}' (${user.email})! ๐" } ?: "โ User not found"
}
}
```
> UserRepository is referenced in UserServiceImpl's constructor
We declare `UserService` with the `@Singleton` annotation:
## HTTP Controller and Koin Application
Finally, we need to create a `@KoinApplication` object and configure our HTTP routes:
```kotlin
@KoinApplication
object KoinUserApplication
```
The `@KoinApplication` annotation marks this as the entry point for Koin's annotation-based configuration. The KSP processor generates configuration that can be used with `withConfiguration()` to initialize Koin.
## Start and Inject
Now let's configure the Ktor application with Koin:
```kotlin
fun Application.main() {
// Install Koin with generated configuration
install(Koin) {
slf4jLogger()
withConfiguration()
}
// Lazy inject UserService
val service by inject()
service.loadUsers()
// Routing section
routing {
get("/hello") {
val userName = call.queryParameters["name"] ?: "Alice"
val user = service.getUserOrNull(userName)
val message = service.prepareHelloMessage(user)
call.respondText(message)
}
}
}
```
**Key Points:**
* `withConfiguration()` - Uses the generated Koin configuration from the annotated application object
* No need to manually call `modules(AppModule().module)` - it's included automatically!
* The `/hello` endpoint accepts an optional `name` query parameter
Let's start Ktor:
```kotlin
fun main(args: Array) {
embeddedServer(Netty, port = 8080) {
main()
}.start(wait = true)
}
```
That's it! You're ready to go. Check these URLs:
- `http://localhost:8080/hello` - Greets Alice (default user)
- `http://localhost:8080/hello?name=Bob` - Greets Bob
:::info
The `@KoinApplication` annotation with `@Configuration` on the module automatically discovers and loads all annotated dependencies at compile time.
:::
---
### Quickstart Ktor (`docs/quickstart/ktor.md`)
---
title: Ktor
---
> Ktor is a framework for building asynchronous servers and clients in connected systems using the powerful Kotlin programming language. We will use Ktor here, to build a simple web application.
Let's go ๐
:::note
update - 2024-10-21
:::
:::tip
Looking for the **annotations version** of this tutorial? Check out [Ktor & Annotations](./ktor-annotations.md) which uses Koin Annotations with Jakarta `@Singleton` for compile-time verification.
:::
## Get the code
:::info
[The source code is available at on Github](https://github.com/InsertKoinIO/koin-getting-started/tree/main/ktor)
:::
## Gradle Setup
First, add the Koin dependency like below:
```kotlin
dependencies {
// Koin for Kotlin apps
implementation("io.insert-koin:koin-ktor:$koin_version")
implementation("io.insert-koin:koin-logger-slf4j:$koin_version")
}
```
## Application Overview
The idea of the application is to manage a list of users, and display it in our `UserApplication` class:
> Users -> UserRepository -> UserService -> UserApplication
## The "User" Data
We will manage a collection of Users. Here is the data class:
```kotlin
data class User(val name: String, val email: String)
```
We create a "Repository" component to manage the list of users (add users or find one by name). Here below, the `UserRepository` interface and its implementation:
```kotlin
interface UserRepository {
fun findUserOrNull(name: String): User?
fun addUsers(users: List)
}
class UserRepositoryImpl : UserRepository {
private val _users = arrayListOf()
override fun findUserOrNull(name: String): User? {
return _users.firstOrNull { it.name == name }
}
override fun addUsers(users: List) {
_users.addAll(users)
}
}
```
## The Koin module
Use the `module` function to declare a Koin module. A Koin module is the place where we define all our components to be injected.
```kotlin
val appModule = module {
}
```
Let's declare our first component. We want a singleton of `UserRepository`, by creating an instance of `UserRepositoryImpl`
```kotlin
val appModule = module {
single() bind UserRepository::class
}
```
:::info
This tutorial uses the **Koin Compiler Plugin DSL** (`single()`) which provides auto-wiring at compile time. See [Compiler Plugin Setup](/docs/setup/compiler-plugin) for configuration.
:::
## The UserService Component
Let's write the UserService component to manage user operations:
```kotlin
interface UserService {
fun getUserOrNull(name: String): User?
fun loadUsers()
fun prepareHelloMessage(user: User?): String
}
class UserServiceImpl(
private val userRepository: UserRepository
) : UserService {
override fun getUserOrNull(name: String): User? = userRepository.findUserOrNull(name)
override fun loadUsers() {
userRepository.addUsers(listOf(
User("Alice", "alice@example.com"),
User("Bob", "bob@example.com"),
User("Charlie", "charlie@example.com")
))
}
override fun prepareHelloMessage(user: User?): String {
return user?.let { "Hello '${user.name}' (${user.email})! ๐" } ?: "โ User not found"
}
}
```
> UserRepository is referenced in UserServiceImpl's constructor
We declare `UserService` in our Koin module. We declare it as a `single` definition:
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
}
```
## HTTP Controller
Finally, we need an HTTP Controller to create the HTTP Route. In Ktor it will be expressed through a Ktor extension function:
```kotlin
fun Application.main() {
// Lazy inject UserService
val service by inject()
service.loadUsers()
// Routing section
routing {
get("/hello") {
val userName = call.queryParameters["name"] ?: "Alice"
val user = service.getUserOrNull(userName)
val message = service.prepareHelloMessage(user)
call.respondText(message)
}
}
}
```
The `/hello` endpoint accepts an optional `name` query parameter. If not provided, it defaults to "Alice".
Example requests:
- `http://localhost:8080/hello` - Greets Alice (default)
- `http://localhost:8080/hello?name=Bob` - Greets Bob
## Declare your dependencies
Let's assemble our components with a Koin module:
```kotlin
val appModule = module {
single() bind UserRepository::class
single() bind UserService::class
}
```
## Start and Inject
Finally, let's start Koin from Ktor:
```kotlin
fun Application.main() {
// Install Koin
install(Koin) {
modules(appModule)
}
// Lazy inject UserService
val service by inject()
service.loadUsers()
// Routing section
routing {
get("/hello") {
val userName = call.queryParameters["name"] ?: "Alice"
val user = service.getUserOrNull(userName)
val message = service.prepareHelloMessage(user)
call.respondText(message)
}
}
}
```
Let's start Ktor:
```kotlin
fun main(args: Array) {
embeddedServer(Netty, port = 8080) {
main()
}.start(wait = true)
}
```
That's it! You're ready to go. Check these URLs:
- `http://localhost:8080/hello` - Greets Alice (default user)
- `http://localhost:8080/hello?name=Bob` - Greets Bob
---
### Setup Annotations Ksp (`docs/setup/annotations-ksp.md`)
---
title: KSP Processor Setup (Deprecated)
---
# KSP Processor Setup for Koin Annotations
:::warning
**`koin-ksp-compiler` is deprecated.** The KSP-based processor for Koin Annotations is replaced by the [Koin Compiler Plugin](/docs/setup/compiler-plugin). **Koin Annotations itself is not deprecated** โ the `koin-annotations` library is now part of the main Koin project and remains fully supported. Only the processor changes.
:::
:::info
**Your annotations stay the same** โ only the build setup changes. See [Migration Guide](#migration-to-koin-compiler-plugin) below.
:::
## Why Migrate?
| Aspect | KSP Processor (`koin-ksp-compiler`) | Koin Compiler Plugin |
|--------|-------------------------------------|----------------------|
| **Generated files** | Visible in build/ | None |
| **Build speed** | โ ๏ธ Slower | Faster |
| **KMP setup** | โ ๏ธ Complex | Simple |
| **Future support** | โ ๏ธ Deprecated | โ
Active development |
| **Your code** | โ ๏ธ Use generated extensions | Use Kotlin Compiler plugin dedicated API |
## When to Use the KSP Processor (Temporary)
Only use `koin-ksp-compiler` if you're:
- Stuck on Kotlin 1.x (upgrade recommended)
- Mid-migration and can't switch yet
- Have specific KSP requirements
## Current KSP Processor Setup (Reference)
If you must use the KSP processor, here's the setup:
### Gradle Setup
```kotlin
// build.gradle.kts
plugins {
id("com.google.devtools.ksp") version "$ksp_version"
}
dependencies {
implementation(platform("io.insert-koin:koin-bom:$koin_version"))
implementation("io.insert-koin:koin-core")
implementation("io.insert-koin:koin-annotations:$koin_ksp_version")
ksp("io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
}
```
### Version Compatibility
| Koin Annotations | KSP Version | Kotlin Version |
|------------------|-------------|----------------|
| 1.4 | 1.9 | 1.9 |
| 2.0 | 2.0 | 2.0 |
| 2.1/2.2 | 2.1/2.2 | 2.1/2.2 |
| 2.3 | 2.3 | Independant |
### Basic Usage
```kotlin
@Single
class MyComponent
@Module
class MyModule
// Import generated extensions
import org.koin.ksp.generated.*
fun main() {
startKoin {
modules(MyModule().module)
}
}
```
### KSP Options
```kotlin
// build.gradle.kts
ksp {
arg("KOIN_CONFIG_CHECK", "true") // Enable compile-time validation
}
```
:::tip
This KSP-based compile-time check has been replaced by native compile-time safety in the **Koin Compiler Plugin**. See [Compile-Time Safety](/docs/reference/koin-compiler/compile-safety) and [Compiler Plugin Setup](/docs/setup/compiler-plugin).
:::
### KMP Setup (Complex)
```kotlin
// shared/build.gradle.kts
plugins {
id("com.google.devtools.ksp")
}
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.insert-koin:koin-core:$koin_version")
implementation("io.insert-koin:koin-annotations:$koin_ksp_version")
}
}
}
dependencies {
// Per-platform KSP configuration required
add("kspAndroid", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
add("kspIosX64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
add("kspIosArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
add("kspIosSimulatorArm64", "io.insert-koin:koin-ksp-compiler:$koin_ksp_version")
}
```
## Migration to Koin Compiler Plugin
### Step 1: Update Kotlin
Ensure you're using Kotlin 2.3.20+:
```kotlin
// build.gradle.kts
plugins {
kotlin("jvm") version "2.3.20-Beta1" // or earlier
}
```
### Step 2: Remove KSP
Remove KSP plugin and dependencies:
```kotlin
// Remove these:
plugins {
// id("com.google.devtools.ksp") // Remove
}
dependencies {
// ksp("io.insert-koin:koin-ksp-compiler:...") // Remove
}
```
### Step 3: Add Compiler Plugin
See the **[Compiler Plugin Setup Guide](/docs/setup/compiler-plugin)** for detailed instructions.
### Step 4: Keep Your Code
**Your annotations stay exactly the same ๐**
```kotlin
// This code doesn't change!
@Singleton
class MyService(val repository: MyRepository)
@Factory
class MyRepository
@KoinViewModel
class MyViewModel(val service: MyService)
@Module
@ComponentScan("com.myapp")
class AppModule
```
### Step 5: Update Koin Startup
With the Compiler Plugin, **no generated code is used**. Replace generated extensions with typed API:
**Before (KSP):**
```kotlin
import org.koin.ksp.generated.*
startKoin {
modules(AppModule().module) // Uses generated extension
}
```
**After (Compiler Plugin):**
```kotlin
@KoinApplication
@ComponentScan("com.myapp")
class MyApp
// Use typed API - no generated code!
startKoin()
// Or with configuration
startKoin {
androidContext(this@MyApplication)
}
```
Available typed APIs:
- `startKoin()` - Start Koin globally with application T
- `koinApplication()` - Create isolated KoinApplication with T
- `koinConfiguration()` - Create KoinConfiguration from T (for Compose KoinApplication, Ktor, etc.)
Where `T` is a class annotated with `@KoinApplication`.
### Step 6: Clean Up
Delete generated files:
```bash
rm -rf build/generated/ksp
```
Rebuild your project.
### What Stays the Same
| Annotation | Status |
|------------|--------|
| `@Singleton` / `@Single` | โ
Same |
| `@Factory` | โ
Same |
| `@Scoped` | โ
Same |
| `@KoinViewModel` | โ
Same |
| `@KoinWorker` | โ
Same |
| `@Named` | โ
Same |
| `@InjectedParam` | โ
Same |
| `@Property` | โ
Same |
| `@Module` | โ
Same |
| `@ComponentScan` | โ
Same |
| `@Configuration` | โ
Same |
### What Changes
| Aspect | KSP Processor | Koin Compiler Plugin |
|--------|---------------|----------------------|
| Build plugin | `com.google.devtools.ksp` | `io.insert-koin.compiler.plugin` |
| Dependencies | `ksp("io.insert-koin:koin-ksp-compiler")` | None required (plugin only) |
| `koin-annotations` version | Separate (`koin-ksp` version) | Same as main Koin version |
| Generated files | Visible in `build/` | None |
| Koin startup | `modules(AppModule().module)` | `startKoin()` |
| KMP setup | Per-platform KSP | Just plugin |
## Timeline
:::warning
The `koin-ksp-compiler` processor will be removed in a future Koin version. We recommend migrating to the Koin Compiler Plugin as soon as possible. The `koin-annotations` library and your `@Singleton` / `@Factory` / `@Module` annotations are not going away โ they're now processed by the Koin Compiler Plugin.
:::
## Help
If you encounter issues during migration:
- Check [Troubleshooting](/docs/reference/troubleshooting)
- Ask on [Slack](https://kotlinlang.slack.com/messages/koin/)
- Open an issue on [GitHub](https://github.com/InsertKoinIO/koin)
## Next Steps
- **[Migration Guide](/docs/migration/from-ksp-to-compiler-plugin)** - Step-by-step migration to Compiler Plugin
- **[Compiler Plugin Setup](/docs/setup/compiler-plugin)** - Complete setup guide
---
### Setup Annotations (`docs/setup/annotations.md`)
---
title: Koin Annotations
---
Setup Koin Annotations for your project
## Current Versions
You can find all Koin packages on [maven central](https://search.maven.org/search?q=io.insert-koin).
Here are the currently available Koin Annotations versions:
- **Stable**: [](https://mvnrepository.com/artifact/io.insert-koin/koin-annotations) - Use for production applications
- **Latest**: [](https://mvnrepository.com/artifact/io.insert-koin/koin-annotations) - Preview of upcoming features
## KSP Plugin
We need the [Google KSP](https://github.com/google/ksp) to work. Follow the official [KSP Setup documentation](https://kotlinlang.org/docs/ksp-quickstart.html).
Just add the Gradle plugin:
```kotlin
plugins {
id("com.google.devtools.ksp") version "$ksp_version"
}
```
**KSP Compatibility**: Koin Annotations 2.3.1 requires KSP `2.3.2`
:::info
**KSP Versioning Change**: Starting from KSP 2.x, the version numbering is now independent from Kotlin versions. Use KSP 2.3.2 for Koin Annotations 2.3.1.
:::
## Using Version Catalogs (Recommended)
In your `gradle/libs.versions.toml`:
```toml
[versions]
koin-annotations = "2.3.1" # Stable version
ksp = "2.3.2" # Required for Koin Annotations 2.3.1
[libraries]
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin-annotations" }
koin-ksp-compiler = { module = "io.insert-koin:koin-ksp-compiler", version.ref = "koin-annotations" }
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
```
## Android & Ktor App KSP Setup
- use KSP Gradle plugin
- add dependency for koin annotations and koin ksp compiler
- set sourceSet
```kotlin
plugins {
alias(libs.plugins.ksp)
}
dependencies {
// Koin
implementation("io.insert-koin:koin-android:$koin_version")
// Koin Annotations
implementation("io.insert-koin:koin-annotations:$koin_annotations_version")
// Koin Annotations KSP Compiler
ksp("io.insert-koin:koin-ksp-compiler:$koin_annotations_version")
}
```
Or with version catalogs:
```kotlin
plugins {
alias(libs.plugins.ksp)
}
dependencies {
// Koin
implementation(libs.koin.android)
// Koin Annotations
implementation(libs.koin.annotations)
// Koin Annotations KSP Compiler
ksp(libs.koin.ksp.compiler)
}
```
## Kotlin Multiplatform Setup
In a standard Kotlin/Kotlin Multiplatform project, you need to setup KSP as follow:
- use KSP Gradle plugin
- add dependency in commonMain for koin annotations
- set sourceSet for commonMain
- add KSP dependencies tasks with koin compiler
- setup compilation task dependency to `kspCommonMainKotlinMetadata`
```kotlin
plugins {
alias(libs.plugins.ksp)
}
kotlin {
sourceSets {
// Add Koin Annotations
commonMain.dependencies {
// Koin
implementation("io.insert-koin:koin-core:$koin_version")
// Koin Annotations
api("io.insert-koin:koin-annotations:$koin_annotations_version")
}
}
// KSP Common sourceSet
sourceSets.named("commonMain").configure {
kotlin.srcDir("build/generated/ksp/metadata/commonMain/kotlin")
}
}
// KSP Tasks
dependencies {
add("kspCommonMainMetadata", "io.insert-koin:koin-ksp-compiler:$koin_annotations_version")
add("kspAndroid", "io.insert-koin:koin-ksp-compiler:$koin_annotations_version")
add("kspIosX64", "io.insert-koin:koin-ksp-compiler:$koin_annotations_version")
add("kspIosArm64", "io.insert-koin:koin-ksp-compiler:$koin_annotations_version")
add("kspIosSimulatorArm64", "io.insert-koin:koin-ksp-compiler:$koin_annotations_version")
}
// Trigger Common Metadata Generation from Native tasks
tasks.matching { it.name.startsWith("ksp") && it.name != "kspCommonMainKotlinMetadata" }.configureEach {
dependsOn("kspCommonMainKotlinMetadata")
}
```
:::info
For complete KMP setup and architecture patterns, see [Koin Annotations KMP](/docs/reference/koin-annotations/kmp).
:::
## Next Steps
Setup complete! Continue to:
- [Getting Started with Koin Annotations](/docs/reference/koin-annotations/start) - Learn how to use annotations in your code
- [Annotations Definitions](/docs/reference/koin-annotations/definitions) - Detailed annotation reference
- [Annotations Inventory](/docs/reference/koin-annotations/annotations-inventory) - Complete list of available annotations
---
### Setup Compiler Plugin (`docs/setup/compiler-plugin.md`)
---
title: Compiler Plugin Setup
---
# Koin Compiler Plugin Setup
The **Koin Compiler Plugin** is the recommended approach for all new Kotlin 2.x projects. It provides auto-wiring, compile-time safety, and a cleaner DSL syntax.
## What is the Compiler Plugin?
The Koin Compiler Plugin is a **native Kotlin Compiler Plugin (K2)** that:
- Auto-detects constructor dependencies
- Provides compile-time analysis
- Works with both DSL and Annotations
- Generates no visible files
See [Introduction to Koin Compiler Plugin](/docs/intro/koin-compiler-plugin) for details on features and benefits.
:::tip IDE Plugin
Install the **[Koin IDE Plugin](https://plugins.jetbrains.com/plugin/26131-koin-dependency-injection-official-)** for Android Studio & IntelliJ IDEA โ code navigation between definitions and injection points, live safety checks, and dependency graph visualization.
:::
## Requirements
- **Kotlin 2.3.20+** (K2 compiler)
- **Gradle 8.x+**
## Setup
### Step 1: Add Koin to Version Catalog
First, check latest versions:
- Koin: [](https://mvnrepository.com/artifact/io.insert-koin/koin-core)
- Koin Compiler Plugin: [](https://mvnrepository.com/artifact/io.insert-koin/koin-compiler-plugin)
Then, in your `gradle/libs.versions.toml`:
```toml
[versions]
koin = ""
koin-plugin = "