Type-safe, annotation-driven DataStore code generation producing zero-boilerplate compile-time implementations from simple interfaces; supports suspend and reactive reads, typed preferences, object serialization, and constructor/reflection instantiation.
Type-safe DataStore — generated from a Kotlin interface, zero boilerplate.
KSP Preferences eliminates the DataStore boilerplate in your Kotlin project.
Annotate a plain Kotlin interface, and the KSP compiler plugin generates a fully-featured, type-safe DataStore implementation at build time — no runtime overhead.
Supports Kotlin Multiplatform (KMP) projects targeting Android, iOS, and Desktop, as well as traditional single-platform Android projects.
Your Interface ──▶ @Preferences + type annotations ──▶ KSP generates Impl
Add to your module's build.gradle.kts:
plugins {
id("com.google.devtools.ksp") version "2.3.6" // match your Kotlin version
}
dependencies {
// Annotations + factory
implementation("io.github.semenciuccosmin:preferences-annotations:2.0.0")
// KSP processor (code generator)
ksp("io.github.semenciuccosmin:preferences-compiler:2.0.0")
// Jetpack DataStore (required at runtime)
implementation("androidx.datastore:datastore-preferences:1.2.1")
}
Add to your shared module's build.gradle.kts:
plugins {
id("com.google.devtools.ksp") version "2.3.6"
}
kotlin {
// Add this to support expect/actual objects
compilerOptions {
freeCompilerArgs.add("-Xexpect-actual-classes")
}
sourceSets {
commonMain.dependencies {
implementation("io.github.semenciuccosmin:preferences-annotations:2.0.0")
implementation()
}
}
}
dependencies {
add(, )
add(, )
add(, )
add(, )
}
Note Both artifacts are published on Maven Central — no extra repository configuration needed.
// suspend context
val name = prefs.getUsername()
prefs.setUsername("Cosmin")
prefs.clear()
// Compose / ViewModel
val name by prefs.getUsernameFlow().collectAsState(initial = "")
PreferencesFactory provides two ways to instantiate the generated implementation, depending on your project setup.
No extra annotations or declarations needed. The factory resolves the generated *Impl class via reflection at runtime:
import io.github.semenciuccosmin.preferences.factory.PreferencesFactory
import io.github.semenciuccosmin.preferences.factory.create
val prefs: UserPreferences = PreferencesFactory.create<UserPreferences>(context)
Note This overload is available on Android and JVM only. On iOS, reflection is not supported — use the KMP approach below.
For KMP projects, use the @ConstructedBy annotation and an expect object declaration. This avoids reflection entirely and works on all platforms including iOS.
Step 1 — Annotate your interface and declare the constructor:
// commonMain
import io.github.semenciuccosmin.preferences.annotations.*
import io.github.semenciuccosmin.preferences.factory.PreferencesConstructor
@Preferences(name = "user_preferences")
@ConstructedBy(UserPreferencesConstructor::class)
interface UserPreferences {
// ... your functions
}
// One-liner — KSP generates the actual implementation on each platform
expect object UserPreferencesConstructor : PreferencesConstructor<UserPreferences>
Step 2 — Instantiate:
// commonMain — works on Android, iOS, and Desktop
import io.github.semenciuccosmin.preferences.factory.PreferencesFactory
import io.github.semenciuccosmin.preferences.factory.create
val prefs: UserPreferences = PreferencesFactory.create(UserPreferencesConstructor, context)
// or directly:
val prefs: UserPreferences = UserPreferencesConstructor.initialize(context)
Note The
contextparameter is required on Android (pass theContext). On iOS and Desktop, passnullor omit it.
| Annotation | Description |
|---|---|
@Preferences(name) | Marks an interface as a DataStore container. becomes the DataStore file name. |
Note The class passed to
@ObjectPreference(clazz = ...)must be annotated with@Serializable(kotlinx.serialization), otherwise serialization will fail at runtime. Object preferences always return a nullable type —nullis yielded when the key is absent.
The repository includes two sample applications demonstrating both usage patterns:
composeApp — KMP (Android + iOS + Desktop)A Compose Multiplatform app that uses @ConstructedBy and expect object for type-safe, reflection-free instantiation across all platforms.
// commonMain
@Preferences(name = PREFERENCES_NAME)
@ConstructedBy(SamplePreferencesConstructor::class)
interface SamplePreferences { /* ... */ }
expect object SamplePreferencesConstructor : PreferencesConstructor<SamplePreferences>
// Instantiation
val prefs = PreferencesFactory.create(SamplePreferencesConstructor, context)
sampleAndroid — Non-KMP AndroidA traditional single-platform Android app that uses the reflection-based factory. No @ConstructedBy, no expect/actual — just annotate and go.
@Preferences(name = PREFERENCES_NAME)
interface SamplePreferences { /* ... */ }
// Instantiation
val prefs: SamplePreferences = PreferencesFactory.create(context)
| Artifact | Group | Version |
|---|---|---|
preferences-annotations |
Gradle (Kotlin DSL)
implementation("io.github.semenciuccosmin:preferences-annotations:2.0.0")
ksp("io.github.semenciuccosmin:preferences-compiler:2.0.0")
Gradle (Groovy DSL)
implementation 'io.github.semenciuccosmin:preferences-annotations:2.0.0'
ksp 'io.github.semenciuccosmin:preferences-compiler:2.0.0'
Maven
<dependency>
<groupId>io.github.semenciuccosmin</groupId>
<artifactId>preferences-annotations</artifactId>
<version>2.0.0</version>
</dependency>
<!-- KSP processor — add via your KSP plugin config, not as a <dependency> -->
| Component | Version |
|---|---|
| Android minSdk | 26 |
| Kotlin | 2.x |
Copyright 2026 Semenciuc Cosmin
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance the License.
You may obtain a copy of the License at
https:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
| Platform | Supported | Instantiation method |
|---|
| Android (KMP) | ✅ | PreferencesFactory.create(constructor, context) |
| iOS (KMP) | ✅ | PreferencesFactory.create(constructor) |
| Desktop/JVM (KMP) | ✅ | PreferencesFactory.create(constructor) |
| Android (non-KMP) | ✅ | PreferencesFactory.create<T>(context) |
import io.github.semenciuccosmin.preferences.annotations.*
import kotlinx.coroutines.flow.Flow
interface UserPreferences {
// One-shot suspending read
suspend fun getUsername(): String
// Reactive Flow read
fun getUsernameFlow(): Flow<String>
// Suspending write
suspend fun setUsername(value: String)
// Clear everything
suspend fun clear()
}
name@ConstructedBy(constructor) | (KMP only) Links the interface to its PreferencesConstructor object for type-safe instantiation. |
| Annotation | Function type | Description |
|---|
@Get | suspend fun foo(): T | One-shot read; returns the stored value or the default. |
@GetFlow | fun foo(): Flow<T> | Reactive read; emits on every change. |
@Set | suspend fun foo(value: T) | Persists the supplied value. |
@Clear | suspend fun foo() | Removes all keys from the DataStore. |
| Annotation | Kotlin type | Default value |
|---|
@StringPreference(key, defaultValue) | String | "" |
@IntPreference(key, defaultValue) | Int | 0 |
@BooleanPreference(key, defaultValue) | Boolean | false |
@LongPreference(key, defaultValue) | Long | 0L |
@FloatPreference(key, defaultValue) | Float | 0f |
@DoublePreference(key, defaultValue) | Double | 0.0 |
@ObjectPreference(key, clazz) | T? | null |
import kotlinx.serialization.Serializable
data class UserProfile(val id: String, val name: String)
interface SamplePreferences {
suspend fun getDarkMode(): Boolean
fun getDarkModeFlow(): Flow<Boolean>
suspend fun setDarkMode(value: Boolean)
suspend fun getLaunchCount(): Int
fun getLaunchCountFlow(): Flow<Int>
suspend fun setLaunchCount(value: Int)
suspend fun getLastSyncMs(): Long
suspend fun getFontScale(): Float
suspend fun getLatitude(): Double
suspend fun getAuthToken(): String
// clazz must be @Serializable — returns null when the key is absent
suspend fun getProfile(): UserProfile?
fun getProfileFlow(): Flow<UserProfile?>
suspend fun setProfile(value: UserProfile)
suspend fun clear()
}
io.github.semenciuccosmin |
2.0.0 |
preferences-compiler | io.github.semenciuccosmin | 2.0.0 |
| KSP |
| matching Kotlin version |
| Jetpack DataStore | 1.1+ |
Surfaced from shared tags and platforms — no rankings paid for.