kmp-persistence
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-10-14
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档manifest.yaml1.2 KB
03 SKILL.md 正文
KMP Persistence Skill
Choosing and wiring local storage in a Kotlin Multiplatform project: multiplatform-settings for flags, DataStore for reactive preferences and small typed documents, Room for anything relational — plus the per-platform file paths, corruption handling and KSP wiring each of them needs.
Storage selection, where the schema lives, migration policy and the rule that no storage type crosses
into domain are normative — see .claude/rules/kmp/persistence.md. This skill implements against
that rule; it does not restate it.
Scope
In scope
- Picking between multiplatform-settings, DataStore (Preferences and typed) and Room.
- Per-platform file paths and secure-storage backings.
- Corruption handling and the error traps specific to each store.
- Room-in-
commonMainsetup:@ConstructedBy,BundledSQLiteDriver, per-target KSP. - Migrating from an existing store.
- Diagnosing "the value is gone after restart" and "every read fails forever".
Out of scope — hand off, do not answer here
- Whether a given piece of data should be persisted at all →
.claude/rules/kmp/persistence.md - Binding the store into the graph →
koin-kmp - Source-set placement and
expect/actualmechanics →kmp-multiplatform-specialist - Caching HTTP responses, DTO→domain mapping →
ktor-client-kmp,.claude/rules/kmp/networking.md Flowoperators,.catchsemantics in general →kotlin-specialist- Server-side SQL and Exposed →
postgresql-exposed-orm
Procedure
- Read the build files first.
libs.versions.tomland the module'sbuild.gradle.kts— report which storage libraries are already present. Adding a second store for data the existing one can hold is the most common wrong answer here. - Classify the data — flags, one typed document, or relational — and pick from the table below.
- Wire the platform piece behind the DI boundary, not inside the class that uses it.
- Verify. Run the module's tests and report the real output; for a migration, prove the old data is still readable.
Choosing
| The data | Store |
|---|---|
| A handful of flags and scalars — theme, locale, onboarding done, a server profile | multiplatform-settings |
The same, but you need a Flow that emits on every change |
DataStore Preferences |
| One typed object with many related fields and a schema that will evolve | DataStore typed + Serializer<T> |
Anything you would write a WHERE or JOIN for, more than ~100 rows, or paging |
Room |
| Payloads above roughly 50 KB per write | Room, or the filesystem |
Two rules of thumb: if a WHERE clause would be useful, it is Room; and DataStore rewrites the
whole file on every edit, so it is the wrong home for anything that grows.
multiplatform-settings
The smallest option, and enough for most settings screens. Settings is an interface in
commonMain; each platform supplies the backing store through DI:
// androidMain — encrypted at rest
actual val platformModule = module {
single<Settings> {
SharedPreferencesSettings(
EncryptedSharedPreferences.create(
"server_profile.encrypted",
MasterKeys.getOrCreate(MasterKeys.AES256_GCM_SPEC),
get<Context>(),
EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
)
)
}
}
// jvmMain — plaintext, user-scoped
actual val platformModule = module {
single<Settings> { PreferencesSettings(Preferences.userRoot().node("com.example.app")) }
}
Note what this asymmetry means: the Desktop backing is not encrypted. If the value is a credential, say so explicitly rather than letting the Android encryption imply the whole app is covered.
It has no Flow API of its own. When the UI must react to a change, either wrap writes in a
MutableStateFlow owned by the storage class, or use DataStore instead — do not poll.
DataStore
Unverified — no consumer project here uses DataStore; this section is adapted from
rcosteira79/android-skills→datastore/SKILL.md.
The same androidx.datastore:datastore-preferences-core runs on Android, iOS and JVM; only the file
path is platform-specific.
Trap 1 — .catch must match IOException specifically. A bare catch swallows
CancellationException, breaking structured concurrency, and hides serializer failures behind a
silently empty state that looks like a first run:
val settings: Flow<UserSettings> = dataStore.data
.catch { e -> if (e is IOException) emit(emptyPreferences()) else throw e }
.map { prefs -> UserSettings(prefs[Keys.DARK_MODE] ?: false, prefs[Keys.LOCALE] ?: "en") }
Trap 2 — typed-store corruption recovery keys off CorruptionException, not IOException. The
serializer must wrap parse failures itself, and the store needs a handler. Without both, one corrupt
file makes every read fail permanently, for that install, forever:
object AppSettingsSerializer : Serializer<AppSettings> {
override val defaultValue = AppSettings()
override suspend fun readFrom(input: InputStream): AppSettings =
try {
Json.decodeFromString(input.readBytes().decodeToString())
} catch (e: SerializationException) {
throw CorruptionException("Cannot read AppSettings", e)
}
override suspend fun writeTo(t: AppSettings, output: OutputStream) =
output.write(Json.encodeToString(t).encodeToByteArray())
}
val store = DataStoreFactory.create(
serializer = AppSettingsSerializer,
corruptionHandler = ReplaceFileCorruptionHandler { AppSettings() },
produceFile = { File(filesDir, "app_settings.json") },
)
Trap 3 — the path. Supply it per platform, and never from the temp directory:
// commonMain
fun createPreferencesDataStore(producePath: () -> String): DataStore<Preferences> =
PreferenceDataStoreFactory.createWithPath(produceFile = { producePath().toPath() })
// android: context.filesDir.resolve(PREFS_FILE).absolutePath
// ios: NSDocumentDirectory via NSFileManager
// jvm: File(System.getProperty("user.home"), ".myapp") — NOT java.io.tmpdir, the OS may wipe it
Never runBlocking on DataStore inside a composable: it parks the main thread on disk I/O and re-runs
on every recomposition. Expose a StateFlow and collect it.
Room in commonMain
Unverified — no consumer project here uses Room; this section is adapted from
rcosteira79/android-skills→android-data-layer/SKILL.md.
Room is KMP-capable from 2.7.0. Three things differ from the Android-only setup:
// commonMain
@Database(entities = [ArticleEntity::class], version = 1, exportSchema = true)
@ConstructedBy(AppDatabaseConstructor::class) // 1. generated per-platform actuals
abstract class AppDatabase : RoomDatabase() {
abstract fun articleDao(): ArticleDao
}
@Suppress("KotlinNoActualForExpect")
expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase>
fun buildDatabase(builder: RoomDatabase.Builder<AppDatabase>): AppDatabase = builder
.setDriver(BundledSQLiteDriver()) // 2. one SQLite version everywhere
.setQueryCoroutineContext(Dispatchers.IO) // 3. Android defaults this; KMP does not
.build()
BundledSQLiteDriver matters because Android's system SQLite version drifts across API levels and
vendors — bundling removes a class of "works on my device" bugs.
KSP must be wired per target. ksp(...) alone is Android-only and produces a database that fails
to build for every other target:
dependencies {
add("kspAndroid", libs.androidx.room.compiler)
add("kspJvm", libs.androidx.room.compiler)
add("kspIosArm64", libs.androidx.room.compiler)
add("kspIosSimulatorArm64", libs.androidx.room.compiler)
}
room { schemaDirectory("$projectDir/schemas") }
The exported schema directory is what makes migrations reviewable — commit it.
Do NOT
- Do NOT let an
Entity,PreferencesorSettingstype appear indomain. - Do NOT use a bare
.catch { }on a DataStore flow. - Do NOT rely on
IOExceptionfor typed-store corruption recovery. - Do NOT put a DataStore or database file in the temp directory.
- Do NOT
runBlockingon storage inside a composable. - Do NOT store more than a few kilobytes in DataStore or multiplatform-settings.
- Do NOT assume a store is encrypted on every platform because it is on one.
- Do NOT bump a Room
versionwithout an accompanying migration and an updated exported schema. - Do NOT wire KSP for Android only in a multi-target module.
Error handling
- The library is not in the version catalog → name the missing artifact and propose the entry; do not hardcode a version.
- Reads fail permanently after one bad write → missing
CorruptionExceptionwrapping or missingReplaceFileCorruptionHandler. Say which, and note that existing installs need the handler to recover. - Values disappear between runs → check the path producer first; the temp directory is the usual cause.
- Room fails to build for a non-Android target → KSP is wired for Android only. Report the
missing
add("ksp<Target>", …)lines. - The data is relational and the project has none of these libraries → say that Room is a real dependency decision, not a detail, and surface it rather than adding it silently.
- The question is "should this be persisted" → point at
.claude/rules/kmp/persistence.mdand stop.
Example
"Remember the selected server profile, including its API token."
- Read
libs.versions.toml; report which storage libraries exist. If multiplatform-settings is already there, do not add DataStore for four fields. - Classify: a handful of scalars, no queries, no reactivity requirement → multiplatform-settings.
- Define a
commonMaininterface (ServerProfileStorage) overSettings; the domain layer sees only that interface. - Bind the backing per platform: encrypted on Android,
Preferences.userRoot()on Desktop — and state plainly that the Desktop side stores the token in plaintext, so the decision is made deliberately rather than by default. - Write a
commonTestround-trip test against an in-memoryMapSettings; run it and report the output.
Expected outcome: one storage abstraction, a per-platform binding, and the security asymmetry stated rather than hidden.
Related Skills
koin-kmp— binding the store and its platform backingkmp-multiplatform-specialist— source sets,expect/actual, KSP per targetktor-client-kmp— the network side of the same data layerkmp-testing— round-trip and migration testskotlin-specialist—Flow,.catch,CancellationExceptiondatabase-optimizer— query shape once the data really is relational
04 同仓库更多 Skills
universal-skill
暂无简介
notion-skill
暂无简介
inline-frontmatter-skill
Hand-authored description that already lives in the body and must not be double-wrapped.
universal-skill
暂无简介
notion-skill
暂无简介
write-a-skill
暂无简介