https://github.com/jordond/stateholder
A simple API for creating and managing state in Kotlin Multiplatform applications.
https://github.com/jordond/stateholder
kotlin kotlin-multiplatform multiplatform state-management
Last synced: about 1 month ago
JSON representation
A simple API for creating and managing state in Kotlin Multiplatform applications.
- Host: GitHub
- URL: https://github.com/jordond/stateholder
- Owner: jordond
- License: mit
- Created: 2023-07-11T16:28:30.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-08T22:00:54.000Z (about 1 month ago)
- Last Synced: 2025-04-09T21:56:59.056Z (about 1 month ago)
- Topics: kotlin, kotlin-multiplatform, multiplatform, state-management
- Language: Kotlin
- Homepage: https://docs.stateholder.dev
- Size: 1.48 MB
- Stars: 4
- Watchers: 3
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# State Holder
[](http://kotlinlang.org)
[](https://github.com/jordond/state-holder/actions/workflows/ci.yml)
[](http://www.apache.org/licenses/LICENSE-2.0)
[](https://github.com/JetBrains/compose-multiplatform)
A simple library for managing state in Kotlin Multiplatform projects, using Kotlin Coroutines
and `StateFlow`.
You can view the KDocs at [docs.stateholder.dev](https://docs.stateholder.dev).
**Note**: This library is still in alpha, documentation is not finished.
## Table of Contents
- [Motivation](#motivation)
- [Planned Features](#planned-features)
- [Setup](#setup)
- [Multiplatform](#multiplatform)
- [Android](#android)
- [Version Catalog](#version-catalog)
- [Usage](#usage)
- [Creating a StateHolder](#creating-a-stateholder)
- [Updating State](#updating-state)
- [Consuming State](#consuming-state)
- [Android Extensions](#android-extensions)
- [License](#license)
## Motivation
State Holder is a library that aims to make state management in Kotlin Multiplatform projects
easier. It provides a simple API for creating and managing state with very little boilerplate. It
provides some extensions to make consuming the state easier (currently only Android).
This library is very un-opinionated and does not force you to use any particular architecture. You
can create your `StateHolder` anywhere you want. This also means you are responsible for scoping the
state, and on Android persisting the state across process death.
### Planned Features
Currently this library is in a very early stage. There are a few more features I wish to add such
as:
- [ ] Support for retaining state across process death on Android
- [x] Extensions for other platforms (iOS, JS, JVM, etc)
- [ ] Documentation
## Setup
You can add this library to your project using Gradle.
### Multiplatform
To add to a multiplatform project, add the dependency to the common source-set:
```kotlin
kotlin {
sourceSets {
commonMain {
dependencies {
implementation("dev.stateholder:core:1.0.1")
// Optional Compose extensions
implementation("dev.stateholder.extensions-compose:1.0.1")
// Optional Voyager extensions
implementation("dev.stateholder.extensions-voyager:1.0.1")
// Optional Android-only extensions (not KMP friendly)
implementation("dev.stateholder.extensions-android:1.0.1")
}
}
}
}
```
### Platforms
| Artifact | Android | Desktop | iOS | macOS | tv/watchOS | Browser | JS (Node) |
|----------------------|:-------:|:-------:|:---:|:-----:|:----------:|:-------:|:---------:|
| `core` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `extensions-compose` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `extensions-voyager` | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
| `extensions-android` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
### Android
For an Android only project, add the dependency to app level `build.gradle.kts`:
```kotlin
dependencies {
// The core library
implementation("dev.stateholder:core:1.0.1")
// Optional Compose extensions
implementation("dev.stateholder:extensions-compose:1.0.1")
// Optional Voyager extensions
implementation("dev.stateholder.extensions-voyager:1.0.1")
// Optional Android extensions
implementation("dev.stateholder:extensions-android:1.0.1")
}
```
### Version Catalog
```toml
[versions]
stateholder = "1.0.1"
[libraries]
stateholder-core = { module = "dev.stateholder:core", version.ref = "stateholder" }
stateholder-extensions-compose = { module = "dev.stateholder:extensions-compose", version.ref = "stateholder" }
stateholder-extensions-android = { module = "dev.stateholder:extensions-android", version.ref = "stateholder" }
stateholder-extensions-voyager = { module = "dev.stateholder:extensions-voyager", version.ref = "stateholder" }
```
## Usage
The `:core` artifact provides the following interfaces:
- `StateHolder`
- Contains the state and provides methods for updating it.
- `StateOwner`
- Exposes a `StateFlow` to consumers.
- `StateProvider`
- Wrapper around `Any` that provides state to a `StateHolder`.
### Creating a StateHolder
WIP
### Updating State
WIP
### Consuming State
WIP
### Android Extensions
WIP
## License
See [LICENSE](LICENSE) for more information.