PreCompose

PreCompose supports several patterns for defining scene routes:

Variable Routes

Use curly braces to define path variables. You can retrieve these from the BackStackEntry using .path<T>(name).

• Standard: route = "/detail/{id}"
• Optional: route = "/detail/{id}?" (matches /detail, /detail/123, or /detail/asd)

Regex Routes

You can constrain path variables using regex syntax after a colon: route = "/detail/{id:[0-9]+}".

• Optional Regex: /user/{id:[0-9]+}? matches /user or /user/123.

Groups

You can group scenes together. Note that group routes and initialRoute only support static routes; they do not support path variables or regex.

group(route = "/group", initialRoute = "/nestedScreen1") {
    scene(route = "/nestedScreen1") { ... }
    scene(route = "/nestedScreen2") { ... }
}

// Variable route example
scene(route = "/detail/{id}") { backStackEntry ->
    val id: Int? = backStackEntry.path<Int>("id")
}

// Regex route example
scene(route = "/detail/{id:[0-9]+}") { backStackEntry ->
    val id: Int? = backStackEntry.path<Int>("id")
}

To persist and restore state within a ViewModel, use SavedStateHolder.

1. Inject SavedStateHolder: Pass the savedStateHolder provided by the viewModel() factory lambda into your ViewModel constructor.
2. Consume State: Use savedStateHolder.consumeRestored(key) to retrieve a previously saved value.
3. Register Provider: Use savedStateHolder.registerProvider(key) to tell the holder how to retrieve the current value for saving when the state is being persisted.

Note: When using SavedStateHolder, you should use the modelClass parameter in the viewModel() function.

// 1. Define ViewModel with SavedStateHolder
class SomeViewModel(private val someKey: Int?, savedStateHolder: SavedStateHolder) : ViewModel() {
    val someSavedValue = MutableStateFlow(savedStateHolder.consumeRestored("someValue") as String? ?: "")
    
    init {
        savedStateHolder.registerProvider("someValue") {
            someSavedValue.value
        }
    }
    
    fun setSomeValue(value: String) {
        someSavedValue.value = value
    }
}

// 2. Use in Compose
val viewModel = viewModel(modelClass = SomeViewModel::class, keys = listOf(someKey)) {
    savedStateHolder ->
    SomeViewModel(someKey, savedStateHolder)
}

When using Koin with PreCompose, do not use a standard Koin inject() for ViewModels, as it will not manage the ViewModel's lifecycle correctly. Instead, use the koinViewModel function provided by the precompose-koin library.

Standard Usage

In your Compose code, call koinViewModel<T> to retrieve your ViewModel. You can pass parameters using parametersOf.

Kotlin/Native Usage

If you are targeting Kotlin/Native, you must explicitly provide the vmClass parameter to koinViewModel because of platform-specific limitations.

Koin Module Definition

Define your ViewModel in your Koin module using factory (or viewModel if using Koin's specific DSL) and use get() to resolve dependencies.

// 1. Define in Koin module
factory { (initialCount: Int) ->
    CounterViewModel(
        initialCount = initialCount,
        counterRepository = get(),
    )
}

// 2. Use in Compose (Standard)
val viewModel = koinViewModel<CounterViewModel> { parametersOf(initialCount) }

// 2. Use in Compose (Kotlin/Native)
val viewModel = koinViewModel(vmClass = CounterViewModel::class) { parametersOf(initialCount) }

To set up navigation in PreCompose, use the NavHost composable and a Navigator instance. The Navigator acts as a replacement for Jetpack Navigation's NavController. You create the navigator using rememberNavigator() and pass it to the NavHost. Inside the NavHost block, you define your navigation graph using scene functions, specifying a route for each destination.

// Define a navigator, which is a replacement for Jetpack Navigation's NavController
val navigator = rememberNavigator()
NavHost(
    // Assign the navigator to the NavHost
    navigator = navigator,
    // Navigation transition for the scenes in this NavHost, this is optional
    navTransition = NavTransition(),
    // The start destination
    initialRoute = "/home",
) {
    // Define a scene to the navigation graph
    scene(
        // Scene's route path
        route = "/home",
        // Navigation transition for this scene, this is optional
        navTransition = NavTransition(),
    ) {
        Text(text = "Hello!")
    }
}