Home

Awesome

Ballast

Opinionated Application State Management framework for Kotlin Multiplatform

Kotlin Version GitHub release (latest by date) Maven Central Intellij Plugin Version

object TodosContract { 
    data class State(
        val loading: Boolean = false, 
        val todos: List<String> = emptyList(), 
    )
  
    sealed interface Inputs {
        data object FetchSavedTodos : Inputs
        data class AddTodo(val text: String) : Inputs
        data class RemoveTodo(val text: String) : Inputs
    }
}

class TodosInputHandler : InputHandler<Inputs, Events, State> {
    override suspend fun InputHandlerScope<Inputs, Events, State>.handleInput(
        input: TodosContract.Inputs
    ) = when (input) {
        is FetchSavedTodos -> { 
            updateState { it.copy(loading = true) }
            val todos = todosApi.fetchTodos()
            updateState { it.copy(loading = false, todos = todos) }
        }
        is AddTodo -> {
            updateState { it.copy(todos = it.todos + input.text) }
        }
        is RemoveTodo -> {
            updateState { it.copy(todos = it.todos - input.text) }
        }
    }
}

@Composable
fun App() { 
    val coroutineScope = rememberCoroutineScope()
    val vm = remember(coroutineScope) { TodosViewModel(coroutineScope) }
    val vmState by vm.observeStates().collectAsState()
    
    LaunchedEffect(vm) { 
        vm.send(TodosContract.FetchSavedTodos)
    }
    
    TodosList(vmState) { vm.trySend(it) }
}

@Composable
fun TodosList(
    vmState: TodosContract.State,
    postInput: (TodosContract.Inputs)->Unit,
) {
    // ...
}

Supported Platforms/Features

Ballast was intentionally designed to not be tied directly to any particular platform or UI toolkit. In fact, while most Kotlin MVI libraries were initially developed for Android and show many artifacts of that initial base, Ballast started as a State Management solution for Compose Desktop.

Because Ballast was initially designed entirely in a non-Android context, it should work in any Kotlin target or platform as long as it works with Coroutines and Flows. However, the following targets are officially supported, in that they have been tested and are known to work there, or have specific features for that platform

Installation

repositories {
    mavenCentral()
  
    // SNAPSHOT builds are available as well at the MavenCentral Snapshots repository
    maven(url = "https://s01.oss.sonatype.org/content/repositories/snapshots")
}

// for plain JVM or Android projects
dependencies {
    implementation("io.github.copper-leaf:ballast-core:{{site.version}}")
    
    implementation("io.github.copper-leaf:ballast-repository:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-saved-state:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-sync:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-undo:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-navigation:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-schedules:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-crash-reporting:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-analytics:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-debugger-client:{{site.version}}")
    
    testImplementation("io.github.copper-leaf:ballast-test:{{site.version}}")
}

// for multiplatform projects
kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("io.github.copper-leaf:ballast-core:{{site.version}}")

                implementation("io.github.copper-leaf:ballast-repository:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-saved-state:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-sync:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-undo:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-navigation:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-schedules:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-crash-reporting:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-analytics:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-debugger-client:{{site.version}}")=
            }
        }
        val commonTest by getting {
            dependencies {
                implementation("io.github.copper-leaf:ballast-test:{{site.version}}")
            }
        }
        val androidMain by getting {
            dependencies {
                implementation("io.github.copper-leaf:ballast-firebase-crashlytics:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-firebase-analytics:{{site.version}}")
            }
        }
    }
}

Documentation

See the website for detailed documentation and usage instructions.

Community Chat

Join us at https://kotlinlang.slack.com in the #ballast channel for support, or to show off what you're building with Ballast!

https://kotlinlang.slack.com/archives/C03GTEJ9Y3E

License

Ballast is licensed under the BSD 3-Clause License, see LICENSE.md.

References

Ballast is not new, it was built upon years of experience building UI applications in Android and observing the direction UI programming has gone in the past few years. The MVI model has proven itself to be robust to a wide array of applications, and there are different implementations of the pattern that focus on different aspects of the pattern.

The following are some of the main libraries I drew inspiration from while using Ballast. If Ballast does not fit your project's needs, maybe one of these will suit you better. See the feature comparison for a better breakdown of the specific features of these libraries, to demonstrate the similarities and differences between them.