0
# Koin Core
1

2
Koin Core is a pragmatic lightweight dependency injection framework for Kotlin multiplatform applications. It provides a DSL-based approach to dependency injection with type-safe resolution, scoped instance management, and zero external dependencies. The framework supports JVM, Android, JavaScript, Native, and WebAssembly targets.
3

4
## Package Information
5

6
- **Package Name**: koin-core
7
- **Package Type**: maven
8
- **Language**: Kotlin  
9
- **Group ID**: io.insert-koin
10
- **Installation**: `implementation("io.insert-koin:koin-core:4.1.0")`
11

12
## Core Imports
13

14
```kotlin
15
import org.koin.core.context.startKoin
16
import org.koin.core.context.stopKoin
17
import org.koin.core.module.Module
18
import org.koin.dsl.module
19
import org.koin.core.component.KoinComponent
20
import org.koin.core.component.inject
21
import org.koin.core.component.get
22
```
23

24
## Basic Usage
25

26
```kotlin
27
import org.koin.core.context.startKoin
28
import org.koin.core.context.stopKoin
29
import org.koin.dsl.module
30
import org.koin.core.component.KoinComponent
31
import org.koin.core.component.inject
32

33
// Define a module with dependencies
34
val appModule = module {
35
    single<DatabaseService> { DatabaseServiceImpl() }
36
    factory<UserRepository> { UserRepositoryImpl(get()) }
37
    single<UserService> { UserServiceImpl(get()) }
38
}
39

40
// Start Koin with modules
41
startKoin {
42
    modules(appModule)
43
}
44

45
// Use dependencies in components
46
class UserController : KoinComponent {
47
    private val userService: UserService by inject()
48
    
49
    fun getUser(id: String) = userService.findById(id)
50
}
51

52
// Stop Koin when done
53
stopKoin()
54
```
55

56
## Architecture
57

58
Koin Core is built around several key components:
59

60
- **Application Context**: Global Koin context (`startKoin`, `stopKoin`) for application-wide dependency management
61
- **Module System**: DSL-based module definition (`module`) for organizing and declaring dependencies  
62
- **Definition Types**: Multiple definition strategies (`single`, `factory`, `scoped`) for different lifecycle patterns
63
- **Component Integration**: Interfaces (`KoinComponent`) and extension functions for seamless dependency injection
64
- **Scope Management**: Hierarchical scoping system for controlling dependency lifecycles and isolation
65
- **Type Safety**: Full Kotlin type safety with reified generics and compile-time dependency resolution
66

67
## Capabilities
68

69
### Application Setup & Configuration
70

71
Core application initialization and configuration functionality. Essential for setting up the dependency injection container and managing application lifecycle.
72

73
```kotlin { .api }
74
fun startKoin(appDeclaration: KoinAppDeclaration): KoinApplication
75
fun startKoin(koinApplication: KoinApplication): KoinApplication
76
fun startKoin(appConfiguration: KoinConfiguration): KoinApplication
77
fun stopKoin()
78

79
fun koinApplication(createEagerInstances: Boolean = true, appDeclaration: KoinAppDeclaration? = null): KoinApplication
80
fun koinApplication(appDeclaration: KoinAppDeclaration?): KoinApplication
81
fun koinApplication(configuration: KoinConfiguration?): KoinApplication
82

83
fun loadKoinModules(module: Module)
84
fun loadKoinModules(modules: List<Module>)
85
fun unloadKoinModules(module: Module)
86
fun unloadKoinModules(modules: List<Module>)
87

88
class KoinApplication {
89
    val koin: Koin
90
    fun modules(vararg modules: Module): KoinApplication
91
    fun modules(modules: List<Module>): KoinApplication
92
    fun properties(values: Map<String, Any>): KoinApplication
93
    fun logger(logger: Logger): KoinApplication
94
    fun printLogger(level: Level = Level.INFO): KoinApplication
95
    fun allowOverride(override: Boolean)
96
    fun createEagerInstances()
97
    fun options(vararg optionValue: Pair<KoinOption, Any>): KoinApplication
98
    fun close()
99
}
100
```
101

102
[Application Setup](./application-setup.md)
103

104
### Module Definition & Dependencies
105

106
DSL-based module definition system for declaring and organizing dependencies. Supports multiple definition types including singletons, factories, and scoped instances.
107

108
```kotlin { .api }
109
fun module(createdAtStart: Boolean = false, moduleDeclaration: ModuleDeclaration): Module
110

111
class Module {
112
    inline fun <reified T> single(
113
        qualifier: Qualifier? = null,
114
        createdAtStart: Boolean = false,
115
        noinline definition: Definition<T>
116
    ): KoinDefinition<T>
117
    
118
    inline fun <reified T> factory(
119
        qualifier: Qualifier? = null,
120
        noinline definition: Definition<T>
121
    ): KoinDefinition<T>
122
    
123
    fun <T> scope(scopeSet: ScopeSet): ScopeDSL
124
}
125

126
interface Definition<T> : (Scope, ParametersHolder) -> T
127
```
128

129
[Module Definition](./module-definition.md)
130

131
### Constructor Reference DSL
132

133
Reflection-free dependency injection using constructor references. Provides type-safe constructor resolution without runtime reflection overhead.
134

135
```kotlin { .api }
136
inline fun <reified R> Module.singleOf(
137
    crossinline constructor: () -> R,
138
    noinline options: DefinitionOptions<R>? = null
139
): KoinDefinition<R>
140

141
inline fun <reified R> Module.factoryOf(
142
    crossinline constructor: () -> R,
143
    noinline options: DefinitionOptions<R>? = null
144
): KoinDefinition<R>
145

146
inline fun <reified R> Scope.new(constructor: () -> R): R
147
```
148

149
[Constructor Reference DSL](./constructor-reference.md)
150

151
### Component Integration & Injection
152

153
Component integration interfaces and extension functions for seamless dependency injection into classes and objects.
154

155
```kotlin { .api }
156
interface KoinComponent {
157
    fun getKoin(): Koin
158
}
159

160
interface KoinScopeComponent : KoinComponent {
161
    val scope: Scope
162
}
163

164
inline fun <reified T> KoinComponent.inject(
165
    qualifier: Qualifier? = null,
166
    mode: LazyThreadSafetyMode = LazyThreadSafetyMode.SYNCHRONIZED,
167
    noinline parameters: ParametersDefinition? = null
168
): Lazy<T>
169

170
inline fun <reified T> KoinComponent.get(
171
    qualifier: Qualifier? = null,
172
    noinline parameters: ParametersDefinition? = null
173
): T
174
```
175

176
[Component Integration](./component-integration.md)
177

178
### Scope Management
179

180
Hierarchical scope system for controlling dependency lifecycles and providing isolated dependency contexts for specific application areas.
181

182
```kotlin { .api }
183
class Scope(
184
    val scopeQualifier: Qualifier,
185
    val id: ScopeID,
186
    val isRoot: Boolean = false,
187
    val scopeArchetype: TypeQualifier? = null,
188
    private val _koin: Koin
189
) {
190
    val closed: Boolean
191
    
192
    inline fun <reified T> inject(
193
        qualifier: Qualifier? = null,
194
        mode: LazyThreadSafetyMode = LazyThreadSafetyMode.SYNCHRONIZED,
195
        noinline parameters: ParametersDefinition? = null
196
    ): Lazy<T>
197
    
198
    inline fun <reified T> get(
199
        qualifier: Qualifier? = null,
200
        noinline parameters: ParametersDefinition? = null
201
    ): T
202
    
203
    inline fun <reified T> getOrNull(
204
        qualifier: Qualifier? = null,
205
        noinline parameters: ParametersDefinition? = null
206
    ): T?
207
    
208
    inline fun <reified T> getAll(): List<T>
209
    inline fun <reified T> getSource(): T?
210
    
211
    inline fun <reified T> declare(
212
        instance: T,
213
        qualifier: Qualifier? = null,
214
        secondaryTypes: List<KClass<*>> = emptyList(),
215
        allowOverride: Boolean = true,
216
        holdInstance: Boolean = false
217
    )
218
    
219
    fun linkTo(vararg scopes: Scope)
220
    fun unlink(vararg scopes: Scope)
221
    fun registerCallback(callback: ScopeCallback)
222
    fun close()
223
    fun getKoin(): Koin
224
}
225

226
typealias ScopeID = String
227
```
228

229
[Scope Management](./scope-management.md)
230

231
### Qualifiers & Parameters
232

233
Type-safe qualifier system for distinguishing between multiple instances of the same type, and parameter injection for runtime dependency configuration.
234

235
```kotlin { .api }
236
interface Qualifier {
237
    val value: String
238
}
239

240
fun named(name: String): Qualifier
241
fun named(name: Enum<*>): Qualifier
242
inline fun <reified T> named(): Qualifier
243

244
class ParametersHolder(
245
    private val values: MutableList<Any?> = mutableListOf(),
246
    private val useIndexedValues: Boolean? = null
247
) {
248
    fun <T> get(index: Int): T
249
    fun <T> getOrNull(index: Int): T?
250
    fun size(): Int
251
    fun isEmpty(): Boolean
252
}
253

254
fun parametersOf(vararg values: Any?): ParametersHolder
255
```
256

257
[Qualifiers & Parameters](./qualifiers-parameters.md)
258

259
### Configuration & Logging
260

261
Application configuration system with structured logging support for debugging and monitoring dependency injection lifecycle.
262

263
```kotlin { .api }
264
class KoinConfiguration(val config: KoinApplication.() -> Unit) {
265
    operator fun invoke(): KoinApplication.() -> Unit
266
    val appDeclaration: KoinApplication.() -> Unit
267
}
268

269
fun koinConfiguration(declaration: KoinAppDeclaration): KoinConfiguration
270

271
abstract class Logger(var level: Level = Level.INFO) {
272
    abstract fun display(level: Level, msg: MESSAGE)
273
    fun debug(msg: MESSAGE)
274
    fun info(msg: MESSAGE)
275
    fun warn(msg: MESSAGE)
276
    fun error(msg: MESSAGE)
277
    fun log(lvl: Level, msg: String)
278
}
279

280
enum class Level {
281
    DEBUG, INFO, WARNING, ERROR, NONE
282
}
283
```
284

285
[Configuration & Logging](./configuration-logging.md)
286

287
### Property Management
288

289
Property injection and management system for configuration values and runtime parameters with type-safe access patterns.
290

291
```kotlin { .api }
292
fun <T : Any> Koin.getProperty(key: String, defaultValue: T): T
293
fun <T : Any> Koin.getProperty(key: String): T?
294
fun Koin.setProperty(key: String, value: Any)
295
fun Koin.deleteProperty(key: String)
296

297
inline fun <reified T> KMutableProperty0<T>.inject()
298
inline fun <reified T> KMutableProperty0<T>.inject(koin: Koin)
299
inline fun <reified T> KMutableProperty0<T>.inject(scope: Scope)
300
```
301

302
[Property Management](./property-management.md)
303

304
### Java Interoperability
305

306
Java-specific API for dependency injection in mixed Kotlin/Java projects with static access patterns.
307

308
```kotlin { .api }
309
object KoinJavaComponent {
310
    @JvmStatic
311
    fun <T> inject(
312
        clazz: Class<*>,
313
        qualifier: Qualifier? = null,
314
        parameters: ParametersDefinition? = null
315
    ): Lazy<T>
316
    
317
    @JvmStatic
318
    fun <T> get(
319
        clazz: Class<*>,
320
        qualifier: Qualifier? = null,
321
        parameters: ParametersDefinition? = null
322
    ): T
323
    
324
    @JvmStatic
325
    fun getKoin(): Koin
326
}
327
```
328

329
[Java Interoperability](./java-interop.md)
330

331
## Types
332

333
### Core Types
334

335
```kotlin { .api }
336
typealias KoinAppDeclaration = KoinApplication.() -> Unit
337
typealias ModuleDeclaration = Module.() -> Unit
338
typealias ParametersDefinition = () -> ParametersHolder
339
typealias DefinitionOptions<T> = BeanDefinition<T>.() -> Unit
340
typealias Definition<T> = Scope.(ParametersHolder) -> T
341
typealias QualifierValue = String
342
typealias ScopeID = String
343
typealias MESSAGE = String
344
typealias OnCloseCallback<T> = (T) -> Unit
345

346
data class StringQualifier(override val value: String) : Qualifier
347
data class TypeQualifier(val kClass: KClass<*>) : Qualifier
348

349
enum class KoinOption {
350
    VIEWMODEL_SCOPE_FACTORY
351
}
352

353
enum class Level {
354
    DEBUG, INFO, WARNING, ERROR, NONE
355
}
356
```
357

358
### Core Interface Types
359

360
```kotlin { .api }
361
interface Qualifier {
362
    val value: QualifierValue
363
}
364

365
interface KoinComponent {
366
    fun getKoin(): Koin
367
}
368

369
interface KoinScopeComponent : KoinComponent {
370
    val scope: Scope
371
}
372

373
abstract class Logger(var level: Level = Level.INFO) {
374
    abstract fun display(level: Level, msg: MESSAGE)
375
}
376
```
377

378
### Exception Types
379

380
```kotlin { .api }
381
class NoDefinitionFoundException(msg: String) : Exception(msg)
382
class InstanceCreationException(msg: String) : Exception(msg)
383
class ClosedScopeException(msg: String) : Exception(msg)
384
class DefinitionOverrideException(msg: String) : Exception(msg)
385
class DefinitionParameterException(msg: String) : Exception(msg)
386
class KoinApplicationAlreadyStartedException(msg: String) : Exception(msg)
387
class MissingPropertyException(msg: String) : Exception(msg)
388
class MissingScopeValueException(msg: String) : Exception(msg)
389
class NoParameterFoundException(msg: String) : Exception(msg)
390
class NoPropertyFileFoundException(msg: String) : Exception(msg)
391
class NoScopeDefFoundException(msg: String) : Exception(msg)
392
class ScopeAlreadyCreatedException(msg: String) : Exception(msg)
393
class ScopeNotCreatedException(msg: String) : Exception(msg)
394
```