0
# Application Setup & Configuration
1

2
This document covers how to set up and configure your Koin application using the `KoinApplication` class and related configuration utilities.
3

4
## Overview
5

6
Koin applications are configured through the `KoinApplication` class, which serves as the main entry point for dependency injection setup. It manages module loading, configuration options, logging, and the overall application lifecycle.
7

8
## Core Setup Functions
9

10
### Creating Koin Applications
11

12
```kotlin { .api }
13
import org.koin.dsl.koinApplication
14

15
// Create and configure a Koin application
16
fun koinApplication(
17
    createEagerInstances: Boolean = true,
18
    appDeclaration: KoinAppDeclaration? = null
19
): KoinApplication
20

21
fun koinApplication(appDeclaration: KoinAppDeclaration?): KoinApplication
22
fun koinApplication(configuration: KoinConfiguration?): KoinApplication
23
fun koinApplication(createEagerInstances: Boolean): KoinApplication
24

25
// Type aliases
26
typealias KoinAppDeclaration = KoinApplication.() -> Unit
27
```
28

29
### Basic Usage Examples
30

31
```kotlin
32
import org.koin.dsl.*
33

34
// Simple application setup
35
val app = koinApplication {
36
    modules(myModule)
37
}
38

39
// With custom configuration
40
val app = koinApplication(createEagerInstances = false) {
41
    allowOverride(true)
42
    printLogger()
43
    modules(listOf(module1, module2))
44
}
45

46
// Access the Koin context
47
val koin = app.koin
48
```
49

50
## KoinApplication Class
51

52
The `KoinApplication` class provides all configuration capabilities for your dependency injection container.
53

54
```kotlin { .api }
55
class KoinApplication private constructor() {
56
    val koin: Koin
57
    
58
    companion object {
59
        fun init(): KoinApplication
60
    }
61
}
62
```
63

64
### Module Management
65

66
Load your dependency modules into the application:
67

68
```kotlin { .api }
69
// Load single module
70
fun modules(modules: Module): KoinApplication
71

72
// Load multiple modules
73
fun modules(vararg modules: Module): KoinApplication
74
fun modules(modules: List<Module>): KoinApplication
75
```
76

77
#### Examples
78

79
```kotlin
80
import org.koin.dsl.*
81

82
val appModule = module { 
83
    single<Repository> { DatabaseRepository() } 
84
}
85
val networkModule = module { 
86
    single<ApiService> { RestApiService() } 
87
}
88

89
// Load single module
90
val app = koinApplication {
91
    modules(appModule)
92
}
93

94
// Load multiple modules
95
val app = koinApplication {
96
    modules(appModule, networkModule)
97
    // or
98
    modules(listOf(appModule, networkModule))
99
}
100
```
101

102
### Configuration Options
103

104
#### Override Control
105

106
Control whether definitions can be overridden:
107

108
```kotlin { .api }
109
fun allowOverride(override: Boolean): Unit
110
```
111

112
```kotlin
113
val app = koinApplication {
114
    allowOverride(true) // Allow definition overrides
115
    modules(myModule)
116
}
117
```
118

119
#### Properties Management
120

121
Load application properties for dependency injection:
122

123
```kotlin { .api }
124
fun properties(values: Map<String, Any>): KoinApplication
125
```
126

127
```kotlin
128
val app = koinApplication {
129
    properties(mapOf(
130
        "db.url" to "jdbc:h2:mem:test",
131
        "api.timeout" to 5000,
132
        "debug.enabled" to true
133
    ))
134
    modules(myModule)
135
}
136
```
137

138
#### Feature Options
139

140
Configure Koin feature flags and options:
141

142
```kotlin { .api }
143
import org.koin.core.option.KoinOption
144

145
fun options(vararg optionValue: Pair<KoinOption, Any>): KoinApplication
146
```
147

148
```kotlin
149
import org.koin.core.option.KoinOption
150

151
val app = koinApplication {
152
    options(
153
        KoinOption.CheckModules to true,
154
        KoinOption.PrintLogger to Level.DEBUG
155
    )
156
    modules(myModule)
157
}
158
```
159

160
### Logging Configuration
161

162
#### Custom Logger
163

164
Set up custom logging for Koin operations:
165

166
```kotlin { .api }
167
import org.koin.core.logger.Logger
168

169
fun logger(logger: Logger): KoinApplication
170
```
171

172
```kotlin
173
import org.koin.core.logger.Logger
174
import org.koin.core.logger.Level
175
import org.koin.core.logger.MESSAGE
176

177
class CustomLogger : Logger() {
178
    override fun display(level: Level, msg: MESSAGE) {
179
        println("[$level] $msg")
180
    }
181
}
182

183
val app = koinApplication {
184
    logger(CustomLogger())
185
    modules(myModule)
186
}
187
```
188

189
#### Print Logger
190

191
Use the built-in print logger:
192

193
```kotlin { .api }
194
import org.koin.core.logger.Level
195

196
fun printLogger(level: Level = Level.INFO): KoinApplication
197
```
198

199
```kotlin
200
import org.koin.core.logger.Level
201

202
val app = koinApplication {
203
    printLogger(Level.DEBUG) // Enable debug logging
204
    modules(myModule)
205
}
206
```
207

208
### Lifecycle Management
209

210
#### Eager Instances
211

212
Create singleton instances marked for eager initialization:
213

214
```kotlin { .api }
215
fun createEagerInstances(): Unit
216
```
217

218
```kotlin
219
val eagerModule = module {
220
    single<DatabaseConnection>(createdAtStart = true) { 
221
        DatabaseConnection() 
222
    }
223
}
224

225
val app = koinApplication {
226
    modules(eagerModule)
227
    createEagerInstances() // Creates DatabaseConnection immediately
228
}
229
```
230

231
#### Application Cleanup
232

233
Close and cleanup resources:
234

235
```kotlin { .api }
236
fun close(): Unit
237
```
238

239
```kotlin
240
val app = koinApplication { modules(myModule) }
241

242
// Use the application...
243

244
// Clean up when done
245
app.close()
246
```
247

248
## Configuration Composition
249

250
### KoinConfiguration Class
251

252
For reusable configuration blocks:
253

254
```kotlin { .api }
255
class KoinConfiguration(val config: KoinApplication.() -> Unit) {
256
    operator fun invoke(): KoinApplication.() -> Unit
257
    val appDeclaration: KoinApplication.() -> Unit
258
}
259

260
fun koinConfiguration(declaration: KoinAppDeclaration): KoinConfiguration
261
```
262

263
#### Creating Reusable Configurations
264

265
```kotlin
266
import org.koin.dsl.*
267

268
// Define reusable configuration
269
val databaseConfig = koinConfiguration {
270
    properties(mapOf("db.url" to "jdbc:postgresql://localhost/mydb"))
271
    modules(databaseModule)
272
}
273

274
val loggingConfig = koinConfiguration {
275
    printLogger(Level.DEBUG)
276
}
277

278
// Apply configurations
279
val app = koinApplication {
280
    includes(databaseConfig, loggingConfig)
281
    modules(appModule)
282
}
283
```
284

285
### Including Configurations
286

287
```kotlin { .api }
288
// Include KoinAppDeclaration configurations
289
fun KoinApplication.includes(vararg configurations: KoinAppDeclaration?): KoinApplication
290

291
// Include KoinConfiguration objects
292
fun KoinApplication.includes(vararg configurations: KoinConfiguration?): KoinApplication
293
```
294

295
#### Advanced Composition Example
296

297
```kotlin
298
// Environment-specific configurations
299
val developmentConfig = koinConfiguration {
300
    allowOverride(true)
301
    printLogger(Level.DEBUG)
302
    properties(mapOf("env" to "development"))
303
}
304

305
val productionConfig = koinConfiguration {
306
    allowOverride(false)
307
    printLogger(Level.ERROR)
308
    properties(mapOf("env" to "production"))
309
}
310

311
// Application setup based on environment
312
val isProduction = System.getProperty("env") == "production"
313
val app = koinApplication {
314
    includes(if (isProduction) productionConfig else developmentConfig)
315
    modules(coreModules)
316
}
317
```
318

319
## Module Loading Behavior
320

321
When modules are loaded, Koin:
322

323
1. **Validates definitions** - Checks for conflicts and circular dependencies
324
2. **Registers definitions** - Adds them to the instance registry
325
3. **Sets up scopes** - Configures any scope definitions
326
4. **Reports timing** - Logs loading duration and definition count (if logging enabled)
327
5. **Handles overrides** - Respects the `allowOverride` setting
328

329
## Best Practices
330

331
### 1. Environment-Based Configuration
332

333
```kotlin
334
class AppConfiguration {
335
    companion object {
336
        fun create(environment: String): KoinConfiguration = when (environment) {
337
            "test" -> koinConfiguration {
338
                allowOverride(true)
339
                modules(testModules)
340
            }
341
            "production" -> koinConfiguration {
342
                allowOverride(false)
343
                printLogger(Level.ERROR)
344
                modules(productionModules)
345
            }
346
            else -> koinConfiguration {
347
                printLogger(Level.DEBUG)
348
                modules(developmentModules)
349
            }
350
        }
351
    }
352
}
353
```
354

355
### 2. Modular Configuration
356

357
```kotlin
358
// Organize by feature
359
val databaseConfig = koinConfiguration { 
360
    modules(databaseModule, migrationModule) 
361
}
362
val networkConfig = koinConfiguration { 
363
    modules(apiModule, httpModule) 
364
}
365
val uiConfig = koinConfiguration { 
366
    modules(viewModelModule, adapterModule) 
367
}
368

369
val app = koinApplication {
370
    includes(databaseConfig, networkConfig, uiConfig)
371
}
372
```
373

374
### 3. Property Management
375

376
```kotlin
377
// Load from external sources
378
val properties = loadPropertiesFromFile("application.properties")
379
val app = koinApplication {
380
    properties(properties)
381
    modules(appModule)
382
}
383
```
384

385
This setup system provides flexible, composable application configuration while maintaining clean separation of concerns across different application layers and environments.