Ballast
Opinionated Application State Management framework for Kotlin Multiplatform
![Intellij Plugin Version](https://img.shields.io/jetbrains/plugin/v/18702-ballast)
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,
) {
}
- This snippet omits some details for brevity, to demonstrate the general idea
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()
maven(url = "https://s01.oss.sonatype.org/content/repositories/snapshots")
}
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}}")
}
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.
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.
- Redux: The OG of the MVI programming model. It also was not the first MVI library, but React+Redux has certainly
been one of the biggest contributors to this pattern's popularity today, especially in JS, but also in many other
tech spaces
- Orbit MVI: A primary source of inspiration for Ballast. This library is mature and well-built, but in my opinion
was built a little too closely to Android, making it less useful on other KMP targets. It also uses terminology from
Redux like "reducer" and "transformer" that are intended to bridge the gap from users familiar with Redux, but are
a bit confusing for developers new to MVI. It is also missing some key features that one would expect from an MVI
library, like a graphical debugger.
- How to write your own MVI system and why you shouldn't: An intro video to the Orbit MVI library, and one of
the best introductions to the MVI model I've seen. By walking you through the thought process behind developing a
simple MVI library, it reinforces the concepts of the pattern and helps you understand how to use a mature MVI library
like Orbit or Ballast.