0
# Application Configuration and Startup
1

2
Core application setup functionality for initializing the Koin container, loading modules, and configuring logging and properties.
3

4
## Capabilities
5

6
### Application Creation
7

8
Create and configure a Koin application instance with modules, properties, and logging.
9

10
```javascript { .api }
11
/**
12
 * Create a new Koin application with optional configuration
13
 * @param createEagerInstances - Whether to create eager instances immediately
14
 * @param appDeclaration - Application configuration function
15
 * @returns KoinApplication instance
16
 */
17
function koinApplication(
18
  createEagerInstances: boolean = true,
19
  appDeclaration?: (app: KoinApplication) => void
20
): KoinApplication;
21

22
/**
23
 * Create a Koin application with configuration function
24
 * @param appDeclaration - Application configuration function
25
 * @returns KoinApplication instance
26
 */
27
function koinApplication(appDeclaration: (app: KoinApplication) => void): KoinApplication;
28

29
/**
30
 * Create a Koin application with configuration object
31
 * @param configuration - KoinConfiguration instance
32
 * @returns KoinApplication instance
33
 */
34
function koinApplication(configuration: KoinConfiguration): KoinApplication;
35
```
36

37
**Usage Examples:**
38

39
```javascript
40
import { koinApplication, module } from "koin-core";
41

42
// Basic application creation
43
const app = koinApplication((app) => {
44
  app.modules([myModule]);
45
  app.printLogger();
46
});
47

48
// With eager instance creation disabled
49
const app = koinApplication(false, (app) => {
50
  app.modules([myModule]);
51
  app.allowOverride(true);
52
});
53

54
// Using configuration object
55
const config = new KoinConfiguration();
56
config.modules([myModule]);
57
const app = koinApplication(config);
58
```
59

60
### Global Application Startup
61

62
Start Koin globally for application-wide dependency injection.
63

64
```javascript { .api }
65
/**
66
 * Start Koin globally with application configuration
67
 * @param appDeclaration - Application configuration function
68
 * @returns KoinApplication instance
69
 */
70
function startKoin(appDeclaration: (app: KoinApplication) => void): KoinApplication;
71

72
/**
73
 * Start Koin globally with pre-configured application
74
 * @param koinApplication - Configured KoinApplication instance  
75
 * @returns KoinApplication instance
76
 */
77
function startKoin(koinApplication: KoinApplication): KoinApplication;
78

79
/**
80
 * Stop the global Koin instance and cleanup all resources
81
 */
82
function stopKoin(): void;
83
```
84

85
**Usage Examples:**
86

87
```javascript
88
import { startKoin, stopKoin, module } from "koin-core";
89

90
// Start with inline configuration
91
startKoin((app) => {
92
  app.modules([appModule, networkModule]);
93
  app.printLogger();
94
  app.properties(new Map([["api.url", "https://api.example.com"]]));
95
});
96

97
// Later, stop the application
98
stopKoin();
99
```
100

101
### Application Configuration
102

103
Configure the Koin application with modules, properties, logging, and behavioral options.
104

105
```javascript { .api }
106
class KoinApplication {
107
  /**
108
   * Load dependency modules into the application
109
   * @param modules - Array of Module instances
110
   * @returns KoinApplication for chaining
111
   */
112
  modules(modules: Module[]): KoinApplication;
113

114
  /**
115
   * Set application properties for dependency injection
116
   * @param properties - Map of property key-value pairs
117
   * @returns KoinApplication for chaining
118
   */
119
  properties(properties: Map<string, any>): KoinApplication;
120

121
  /**
122
   * Configure logging with custom logger
123
   * @param logger - Logger instance
124
   * @returns KoinApplication for chaining
125
   */
126
  logger(logger: Logger): KoinApplication;
127

128
  /**
129
   * Use default console logger with specified level
130
   * @param level - Log level (default: INFO)
131
   * @returns KoinApplication for chaining
132
   */
133
  printLogger(level?: Level): KoinApplication;
134

135
  /**
136
   * Allow definition override for testing and configuration
137
   * @param override - Whether to allow overriding definitions
138
   * @returns KoinApplication for chaining
139
   */
140
  allowOverride(override: boolean): KoinApplication;
141

142
  /**
143
   * Create eager instances immediately after application start
144
   * @returns KoinApplication for chaining
145
   */
146
  createEagerInstances(): KoinApplication;
147

148
  /**
149
   * Close the application and cleanup all resources
150
   */
151
  close(): void;
152

153
  /**
154
   * Get the underlying Koin container for direct access
155
   */
156
  koin: Koin;
157
}
158
```
159

160
**Usage Examples:**
161

162
```javascript
163
import { koinApplication, Level } from "koin-core";
164

165
const app = koinApplication((app) => {
166
  app
167
    .modules([coreModule, apiModule, dbModule])
168
    .properties(new Map([
169
      ["database.url", "mongodb://localhost:27017"],
170
      ["api.timeout", 5000],
171
      ["debug.enabled", true]
172
    ]))
173
    .printLogger(Level.DEBUG)
174
    .allowOverride(false)
175
    .createEagerInstances();
176
});
177

178
// Access the underlying Koin container
179
const koin = app.koin;
180
const service = koin.get("MyService");
181
```
182

183
### Configuration Helper
184

185
Create reusable configuration objects for application setup.
186

187
```javascript { .api }
188
/**
189
 * Create a reusable configuration object
190
 * @param declaration - Configuration function
191
 * @returns KoinConfiguration instance
192
 */
193
function koinConfiguration(declaration: (config: KoinConfiguration) => void): KoinConfiguration;
194

195
class KoinConfiguration {
196
  /**
197
   * Convert configuration to application declaration
198
   * @returns Application declaration function
199
   */
200
  invoke(): (app: KoinApplication) => void;
201

202
  /**
203
   * Export configuration as application declaration
204
   */
205
  appDeclaration: (app: KoinApplication) => void;
206
}
207
```
208

209
**Usage Examples:**
210

211
```javascript
212
import { koinConfiguration, koinApplication } from "koin-core";
213

214
// Create reusable configuration
215
const appConfig = koinConfiguration((config) => {
216
  config.modules([sharedModule, utilsModule]);
217
  config.printLogger();
218
  config.allowOverride(true);
219
});
220

221
// Use configuration with application
222
const app = koinApplication(appConfig);
223

224
// Or use the app declaration directly
225
const app2 = koinApplication(appConfig.appDeclaration);
226
```
227

228
### Runtime Module Management
229

230
Load and unload modules dynamically during application runtime.
231

232
```javascript { .api }
233
/**
234
 * Load additional modules into running application
235
 * @param modules - Modules to load
236
 */
237
function loadKoinModules(modules: Module[]): void;
238

239
/**
240
 * Load single module into running application
241
 * @param module - Module to load
242
 */
243
function loadKoinModules(module: Module): void;
244

245
/**
246
 * Unload modules from running application
247
 * @param modules - Modules to unload
248
 */
249
function unloadKoinModules(modules: Module[]): void;
250

251
/**
252
 * Unload single module from running application
253
 * @param module - Module to unload
254
 */
255
function unloadKoinModules(module: Module): void;
256
```
257

258
**Usage Examples:**
259

260
```javascript
261
import { startKoin, loadKoinModules, unloadKoinModules, module } from "koin-core";
262

263
// Start with basic modules
264
startKoin((app) => {
265
  app.modules([coreModule]);
266
});
267

268
// Load additional modules at runtime
269
const featureModule = module((builder) => {
270
  builder.single(() => new FeatureService());
271
});
272

273
loadKoinModules([featureModule]);
274

275
// Later, unload the module
276
unloadKoinModules([featureModule]);
277
```
278

279
## Types
280

281
```javascript { .api }
282
/** Function type for application configuration */
283
type KoinAppDeclaration = (app: KoinApplication) => void;
284

285
/** Log levels for application logging */
286
enum Level {
287
  DEBUG = "DEBUG",
288
  INFO = "INFO",
289
  WARNING = "WARNING", 
290
  ERROR = "ERROR",
291
  NONE = "NONE"
292
}
293

294
/** Exception thrown when Koin application is already started */
295
class KoinApplicationAlreadyStartedException extends Error {
296
  constructor(message: string);
297
}
298
```