0
# Application Setup & Configuration
1

2
Core application initialization and configuration functionality for setting up the Koin dependency injection container and managing the application lifecycle.
3

4
## Capabilities
5

6
### Application Initialization
7

8
Start the global Koin context with module and configuration setup.
9

10
```kotlin { .api }
11
/**
12
 * Start Koin with application configuration
13
 * @param appDeclaration - Configuration block for KoinApplication setup
14
 * @return KoinApplication instance
15
 */
16
fun startKoin(appDeclaration: KoinAppDeclaration): KoinApplication
17

18
/**
19
 * Start Koin with pre-configured KoinApplication
20
 * @param koinApplication - Pre-configured KoinApplication instance
21
 * @return KoinApplication instance
22
 */
23
fun startKoin(koinApplication: KoinApplication): KoinApplication
24

25
/**
26
 * Stop the global Koin context and clean up resources
27
 */
28
fun stopKoin()
29

30
/**
31
 * Create KoinApplication instance with configuration
32
 * @param createEagerInstances - Whether to create eager instances (default: true)
33
 * @param appDeclaration - Optional configuration block
34
 * @return KoinApplication instance
35
 */
36
fun koinApplication(createEagerInstances: Boolean = true, appDeclaration: KoinAppDeclaration? = null): KoinApplication
37

38
/**
39
 * Create KoinApplication instance with configuration block
40
 * @param appDeclaration - Configuration block
41
 * @return KoinApplication instance
42
 */
43
fun koinApplication(appDeclaration: KoinAppDeclaration?): KoinApplication
44

45
/**
46
 * Create KoinApplication instance with KoinConfiguration
47
 * @param configuration - KoinConfiguration instance
48
 * @return KoinApplication instance
49
 */
50
fun koinApplication(configuration: KoinConfiguration?): KoinApplication
51
```
52

53
**Usage Examples:**
54

55
```kotlin
56
import org.koin.core.context.startKoin
57
import org.koin.core.context.stopKoin
58
import org.koin.dsl.module
59
import org.koin.dsl.koinApplication
60

61
// Simple startup with modules
62
startKoin {
63
    modules(appModule, networkModule)
64
}
65

66
// Advanced startup with configuration
67
startKoin {
68
    modules(listOf(appModule, networkModule))
69
    printLogger(Level.DEBUG)
70
    allowOverride(false)
71
    properties(mapOf("api.url" to "https://api.example.com"))
72
}
73

74
// Using koinApplication for more control
75
val app = koinApplication {
76
    modules(appModule)
77
    printLogger(Level.INFO)
78
}
79
startKoin(app)
80

81
// Pre-configured application
82
val configuredApp = koinApplication(createEagerInstances = false) {
83
    modules(testModules)
84
    allowOverride(true)
85
}
86
startKoin(configuredApp)
87

88
// Programmatic startup
89
val koinApp = koinApplication {
90
    modules(appModule)
91
}
92
startKoin(koinApp)
93

94
// Shutdown
95
stopKoin()
96
```
97

98
### Module Loading and Unloading
99

100
Dynamic module management for runtime loading and unloading of dependency modules.
101

102
```kotlin { .api }
103
/**
104
 * Load module into running Koin application
105
 * @param module - Module to load
106
 */
107
fun loadKoinModules(module: Module)
108

109
/**
110
 * Load multiple modules into running Koin application
111
 * @param modules - List of modules to load
112
 */
113
fun loadKoinModules(modules: List<Module>)
114

115
/**
116
 * Unload module from running Koin application
117
 * @param module - Module to unload
118
 */
119
fun unloadKoinModules(module: Module)
120

121
/**
122
 * Unload multiple modules from running Koin application  
123
 * @param modules - List of modules to unload
124
 */
125
fun unloadKoinModules(modules: List<Module>)
126
```
127

128
**Usage Examples:**
129

130
```kotlin
131
import org.koin.core.context.loadKoinModules
132
import org.koin.core.context.unloadKoinModules
133

134
// Load additional modules at runtime
135
fun enableFeature() {
136
    val featureModule = module {
137
        single<FeatureService> { FeatureServiceImpl() }
138
    }
139
    loadKoinModules(featureModule)
140
}
141

142
// Load multiple modules
143
fun loadPluginModules(plugins: List<Plugin>) {
144
    val pluginModules = plugins.map { plugin ->
145
        module {
146
            single { plugin.getService() }
147
        }
148
    }
149
    loadKoinModules(pluginModules)
150
}
151

152
// Unload modules when feature is disabled
153
fun disableFeature() {
154
    unloadKoinModules(featureModule)
155
}
156
```
157

158
### KoinApplication Configuration
159

160
Configure the Koin application with modules, properties, and options.
161

162
```kotlin { .api }
163
class KoinApplication {
164
    /**
165
     * Get the Koin instance
166
     */
167
    val koin: Koin
168
    
169
    companion object {
170
        /**
171
         * Initialize new KoinApplication
172
         * @return KoinApplication instance
173
         */
174
        fun init(): KoinApplication
175
    }
176
    /**
177
     * Add modules to the application
178
     * @param modules - Variable number of Module instances
179
     * @return KoinApplication for chaining
180
     */
181
    fun modules(vararg modules: Module): KoinApplication
182
    
183
    /**
184
     * Add modules to the application
185
     * @param modules - List of Module instances
186
     * @return KoinApplication for chaining
187
     */
188
    fun modules(modules: List<Module>): KoinApplication
189
    
190
    /**
191
     * Set properties for the application
192
     * @param values - Map of property key-value pairs
193
     * @return KoinApplication for chaining
194
     */
195
    fun properties(values: Map<String, Any>): KoinApplication
196
    
197
    /**
198
     * Set custom logger for the application
199
     * @param logger - Logger instance
200
     * @return KoinApplication for chaining
201
     */
202
    fun logger(logger: Logger): KoinApplication
203
    
204
    /**
205
     * Enable console printing logger with specified level
206
     * @param level - Log level (DEBUG, INFO, WARNING, ERROR, NONE)
207
     * @return KoinApplication for chaining
208
     */
209
    fun printLogger(level: Level = Level.INFO): KoinApplication
210
    
211
    /**
212
     * Allow definition override (disabled by default)
213
     * @param override - Whether to allow overriding existing definitions
214
     */
215
    fun allowOverride(override: Boolean)
216
    
217
    /**
218
     * Create eager instances for definitions marked as createdAtStart
219
     */
220
    fun createEagerInstances()
221
    
222
    /**
223
     * Set options for the application
224
     * @param optionValue - Variable number of option pairs
225
     * @return KoinApplication for chaining
226
     */
227
    fun options(vararg optionValue: Pair<KoinOption, Any>): KoinApplication
228
    
229
    /**
230
     * Close the application and clean up resources
231
     */
232
    fun close()
233
    
234
    companion object {
235
        /**
236
         * Create a new KoinApplication instance
237
         * @return Empty KoinApplication ready for configuration
238
         */
239
        fun init(): KoinApplication
240
    }
241
}
242
```
243

244
**Usage Examples:**
245

246
```kotlin
247
import org.koin.core.KoinApplication
248
import org.koin.core.logger.Level
249
import org.koin.dsl.koinApplication
250

251
// Fluent configuration
252
val app = koinApplication {
253
    modules(coreModule, dataModule)
254
    properties(mapOf(
255
        "db.url" to "jdbc:postgresql://localhost/mydb",
256
        "api.timeout" to 30
257
    ))
258
    printLogger(Level.DEBUG)
259
    allowOverride(true)
260
    createEagerInstances()
261
}
262

263
// Programmatic configuration
264
val app = KoinApplication.init()
265
    .modules(coreModule)
266
    .logger(CustomLogger())
267
    .properties(loadProperties())
268
    .createEagerInstances()
269

270
// Close when done
271
app.close()
272
```
273

274
### Application Factory Function
275

276
Create KoinApplication instances using DSL syntax.
277

278
```kotlin { .api }
279
/**
280
 * Create a KoinApplication instance with DSL configuration
281
 * @param createEagerInstances - Whether to create eager instances immediately
282
 * @param appDeclaration - Optional configuration block
283
 * @return Configured KoinApplication instance
284
 */
285
fun koinApplication(
286
    createEagerInstances: Boolean = true,
287
    appDeclaration: KoinAppDeclaration? = null
288
): KoinApplication
289
```
290

291
**Usage Examples:**
292

293
```kotlin
294
import org.koin.dsl.koinApplication
295

296
// Simple creation
297
val app = koinApplication {
298
    modules(myModule)
299
}
300

301
// With eager instance control
302
val app = koinApplication(createEagerInstances = false) {
303
    modules(myModule)
304
    printLogger()
305
}
306

307
// Just create empty application
308
val app = koinApplication(createEagerInstances = false)
309
```
310

311
### Module Loading & Unloading
312

313
Dynamically load and unload modules in the global context.
314

315
```kotlin { .api }
316
/**
317
 * Load additional modules into the global Koin context
318
 * @param module - Single module to load
319
 */
320
fun loadKoinModules(module: Module)
321

322
/**
323
 * Load additional modules into the global Koin context
324
 * @param modules - List of modules to load
325
 */
326
fun loadKoinModules(modules: List<Module>)
327

328
/**
329
 * Unload modules from the global Koin context
330
 * @param module - Single module to unload
331
 */
332
fun unloadKoinModules(module: Module)
333

334
/**
335
 * Unload modules from the global Koin context
336
 * @param modules - List of modules to unload
337
 */
338
fun unloadKoinModules(modules: List<Module>)
339
```
340

341
**Usage Examples:**
342

343
```kotlin
344
import org.koin.core.context.loadKoinModules
345
import org.koin.core.context.unloadKoinModules
346

347
// Load single module
348
loadKoinModules(featureModule)
349

350
// Load multiple modules
351
loadKoinModules(listOf(featureAModule, featureBModule))
352

353
// Unload modules
354
unloadKoinModules(featureModule)
355
unloadKoinModules(listOf(featureAModule, featureBModule))
356
```
357

358
## Types
359

360
```kotlin { .api }
361
typealias KoinAppDeclaration = KoinApplication.() -> Unit
362

363
enum class Level {
364
    DEBUG, INFO, WARNING, ERROR, NONE
365
}
366

367
abstract class Logger(val level: Level = Level.INFO) {
368
    abstract fun display(level: Level, msg: MESSAGE)
369
    fun debug(msg: MESSAGE)
370
    fun info(msg: MESSAGE) 
371
    fun warn(msg: MESSAGE)
372
    fun error(msg: MESSAGE)
373
    fun log(level: Level, msg: MESSAGE)
374
    fun isAt(level: Level): Boolean
375
}
376

377
typealias MESSAGE = String
378

379
class EmptyLogger : Logger(Level.NONE)
380
```