0
# Application Setup
1

2
Core functions for setting up Koin contexts within Compose applications, providing both standard and multiplatform configurations with automatic platform-specific optimizations.
3

4
## Capabilities
5

6
### KoinApplication
7

8
Start a new Koin Application context and setup Compose context for dependency injection throughout the hierarchy.
9

10
```kotlin { .api }
11
/**
12
 * Start a new Koin Application context and setup Compose context
13
 * @param application Koin Application declaration lambda
14
 * @param content Following compose function
15
 * @throws KoinApplicationAlreadyStartedException if default context already set
16
 */
17
@Composable
18
fun KoinApplication(
19
    application: KoinAppDeclaration,
20
    content: @Composable () -> Unit
21
)
22
```
23

24
**Usage Examples:**
25

26
```kotlin
27
@Composable
28
fun App() {
29
    KoinApplication(application = {
30
        // Standard Koin configuration
31
        modules(
32
            appModule,
33
            networkModule,
34
            databaseModule
35
        )
36
        
37
        // Optional: Custom logger
38
        logger(PrintLogger(Level.DEBUG))
39
        
40
        // Optional: Properties
41
        properties(mapOf("api.url" to "https://api.example.com"))
42
    }) {
43
        // Your entire Compose UI hierarchy
44
        NavHost(navController = rememberNavController()) {
45
            // Navigation setup
46
        }
47
    }
48
}
49
```
50

51
### KoinMultiplatformApplication
52

53
Start Koin application with multiplatform configuration that automatically handles Android context and logger setup based on the target platform.
54

55
```kotlin { .api }
56
/**
57
 * Start Koin application with multiplatform configuration
58
 * Handles Android context/logger automatically
59
 * @param config Koin Application Configuration
60
 * @param logLevel Logger level (default: INFO)
61
 * @param content Following compose function
62
 * @throws KoinApplicationAlreadyStartedException
63
 */
64
@Composable
65
@KoinExperimentalAPI
66
fun KoinMultiplatformApplication(
67
    config: KoinConfiguration,
68
    logLevel: Level = Level.INFO,
69
    content: @Composable () -> Unit
70
)
71
```
72

73
**Usage Examples:**
74

75
```kotlin
76
@Composable
77
fun MultiplatformApp() {
78
    KoinMultiplatformApplication(
79
        config = koinConfiguration {
80
            modules(sharedModule, platformModule)
81
        },
82
        logLevel = Level.DEBUG
83
    ) {
84
        SharedContent()
85
    }
86
}
87
```
88

89
### KoinIsolatedContext
90

91
Provides isolated Koin context via CompositionLocalProvider without starting a global Koin application.
92

93
```kotlin { .api }
94
/**
95
 * Provides isolated Koin context via CompositionLocalProvider
96
 * @param context Koin isolated context created with koinApplication()
97
 * @param content Child composable
98
 */
99
@Composable
100
fun KoinIsolatedContext(
101
    context: KoinApplication,
102
    content: @Composable () -> Unit
103
)
104
```
105

106
**Usage Examples:**
107

108
```kotlin
109
@Composable
110
fun IsolatedFeature() {
111
    val isolatedContext = koinApplication {
112
        modules(featureModule)
113
    }
114
    
115
    KoinIsolatedContext(context = isolatedContext) {
116
        FeatureContent()
117
    }
118
}
119
```
120

121
### KoinApplicationPreview
122

123
Lightweight Koin application specifically designed for Compose previews, allowing parallel recomposition without conflicts.
124

125
```kotlin { .api }
126
/**
127
 * Lightweight Koin application for Compose previews
128
 * Allows parallel recomposition
129
 * @param application Koin application config
130
 * @param content Compose content
131
 */
132
@Composable
133
fun KoinApplicationPreview(
134
    application: KoinAppDeclaration,
135
    content: @Composable () -> Unit
136
)
137
```
138

139
**Usage Examples:**
140

141
```kotlin
142
@Preview
143
@Composable
144
fun UserScreenPreview() {
145
    KoinApplicationPreview(application = {
146
        modules(previewModule)
147
    }) {
148
        UserScreen()
149
    }
150
}
151

152
val previewModule = module {
153
    single<UserRepository> { MockUserRepository() }
154
    single<ApiService> { MockApiService() }
155
}
156
```
157

158
### KoinContext (Deprecated)
159

160
Use Compose with existing Koin context. This function is deprecated as Compose Koin context is now automatically set up with other functions.
161

162
```kotlin { .api }
163
/**
164
 * Use Compose with existing Koin context
165
 * @deprecated KoinContext is not needed anymore. This can be removed. 
166
 *            Compose Koin context is setup with StartKoin()
167
 */
168
@Composable
169
@Deprecated("KoinContext is not needed anymore. This can be removed. Compose Koin context is setup with StartKoin()")
170
fun KoinContext(
171
    koin: Koin = retrieveDefaultInstance(),
172
    content: @Composable () -> Unit
173
)
174
```
175

176
## Platform-Specific Behavior
177

178
### Android Platform
179
- **Automatic Context Injection**: Uses `LocalContext.current.applicationContext` to provide Android context to Koin
180
- **Android Logger**: Automatically configures Android-specific logging
181
- **Lifecycle Integration**: Integrates with Android Activity/Fragment lifecycle management
182

183
### Other Platforms (JVM, JS, Native, WASM-JS)
184
- **Print Logger**: Uses standard console/print logging
185
- **Standard Initialization**: Uses `KoinPlatform.getKoin()` for context access
186
- **Cross-Platform Compatibility**: Full Kotlin Multiplatform support
187

188
## Error Handling
189

190
All application setup functions may throw `KoinApplicationAlreadyStartedException` if attempting to start Koin when a default context is already set. This typically occurs when:
191

192
- Calling `KoinApplication` multiple times at the root level
193
- Mixing `startKoin` with `KoinApplication`
194
- Nesting application setup functions incorrectly
195

196
```kotlin
197
@Composable
198
fun SafeApp() {
199
    try {
200
        KoinApplication(application = { modules(appModule) }) {
201
            Content()
202
        }
203
    } catch (e: KoinApplicationAlreadyStartedException) {
204
        // Handle multiple initialization attempts
205
        Content() // Use existing Koin context
206
    }
207
}
208
```
209

210
## Best Practices
211

212
1. **Single Application Setup**: Use only one application setup function at your app's root level
213
2. **Preview Support**: Use `KoinApplicationPreview` for Compose previews to avoid conflicts
214
3. **Multiplatform Projects**: Prefer `KoinMultiplatformApplication` for automatic platform handling
215
4. **Isolated Features**: Use `KoinIsolatedContext` for self-contained feature modules
216
5. **Testing**: Create separate test modules for preview and testing scenarios