Home

worker-kmp

WorkManager for Kotlin Multiplatform. One commonMain API. Out-of-box support for Android, iOS, Desktop, and Web.

Why worker-kmp

Without worker-kmp	With worker-kmp
Write 4 different scheduling implementations (WorkManager, BGTaskScheduler, JVM coroutines, Web Workers)	Write one CoroutineWorker subclass in commonMain
4 different per-platform init calls before startKoin	One workKoinModule(config, workers, factory) — done
Different retry/constraint/observability semantics per platform	One Constraints builder, one RetryConfig, one WorkObserver SAM — works everywhere
Per-platform UI for work monitoring	WorkSchedulerScreen + WorkMonitorScreen in Compose Multiplatform

Out-of-box platform support

Platform	Mechanism	True background?
Android (API 21+)	androidx.work.WorkManager + JobScheduler	✓ OS-scheduled, persistent
iOS (13+)	BGTaskScheduler (Processing + AppRefresh + ContinuedProcessing 17+)	✓ OS-managed, opaque cadence
Desktop (JVM 11+)	OS-scheduler daemon (Windows Task Scheduler / macOS launchd / Linux systemd-user)	✓ Survives app close + reboot
Web (browsers)	Service Worker + Web Push (Chrome/Firefox/Safari 16.4+/Edge)	✓ Server-cron-driven

See True Background Matrix for full per-platform-variant detail.

Quick start

1. Add the dependency

// gradle/libs.versions.toml
worker-kmp = "3.0.0"

// commonMain build.gradle.kts
dependencies {
    api(libs.worker.kmp)
    api(libs.worker.koin)
    // Optional add-ons:
    implementation(libs.worker.compose)    // Compose Multiplatform UI
    implementation(libs.worker.store5)     // Store5 bridge
    implementation(libs.worker.storeflow)  // Offline-first patterns
}

2. Define a worker (commonMain)

class DataSyncWorker(
    context: WorkerContext,
    private val api: ApiClient,
) : CoroutineWorker(context) {
    override suspend fun doWork(): WorkResult {
        val endpoint = inputData.getString("endpoint") ?: return WorkResult.failure()
        return runCatching { api.sync(endpoint) }
            .fold(
                onSuccess = { WorkResult.success() },
                onFailure = { WorkResult.retry(it.message) },
            )
    }
}

3. Wire up Koin (commonMain — one call, every platform)

startKoin {
    modules(
        workKoinModule(
            config = WorkerConfig(logLevel = LogLevel.INFO),
            workers = workerRegistry {
                register<DataSyncWorker> { ctx -> DataSyncWorker(ctx, koin.get()) }
            },
            factory = androidWorkManagerFactory(this@Application),  // or iosWorkManagerFactory() / desktopWorkManagerFactory() / webWorkManagerFactory()
        ),
        appModule,
    )
}

4. Schedule + observe (commonMain)

val workManager: WorkManager = get()
val id = workManager.enqueue(oneTimeWorkRequest<DataSyncWorker> {
    setConstraints(Constraints { setRequiredNetworkType(NetworkType.CONNECTED) })
    setInputData(workDataOf("endpoint" to "/api/sync"))
})
workManager.getWorkInfosByTag("sync").collect { infos ->
    infos.forEach { println("${it.id}: ${it.state}") }
}

That's the entire setup. Same code shape on Android, iOS, Desktop, Web.

Compose Multiplatform UI components

@Composable
fun WorkDashboard() {
    WorkSchedulerScreen(onWorkScheduled = { id -> /* … */ })
    WorkMonitorScreen(tag = "sync")
}

Full Compose API →

Library modules

Module	Coordinates	Purpose
cmp-worker-kmp	io.github.mobilebytelabs:worker-kmp:3.0.0	Core API — WorkManager, CoroutineWorker, types
cmp-worker-koin	:worker-koin:3.0.0	Koin DI module — workKoinModule(...)
cmp-worker-compose	:worker-compose:3.0.0	Compose Multiplatform UI
cmp-worker-test	:worker-test:3.0.0	Test utilities — TestWorkManager
cmp-worker-android	:worker-android:3.0.0	Android actual (auto-wired)
cmp-worker-ios	:worker-ios:3.0.0	iOS actual (auto-wired)
cmp-worker-desktop	:worker-desktop:3.0.0	Desktop actual (auto-wired)
cmp-worker-web	:worker-web:3.0.0	Web actual (auto-wired)
cmp-worker-store5	:worker-store5:3.0.0	Store5 bridge (optional)
cmp-worker-storeflow	:worker-storeflow:3.0.0	Offline-first patterns (optional)
cmp-worker-desktop-daemon	:worker-desktop-daemon:3.0.0	Desktop OS-scheduler daemon (optional)
cmp-worker-web-push	:worker-web-push:3.0.0	Web Push universal background (optional)

Where next

• 📚 Installation — Gradle + Maven setup with Compose Multiplatform
• 🚀 Quick Start — first worker in 60 seconds
• 🧩 Convention Plugin (build-logic) — copy-and-adopt Kotlin source for projects that share worker-kmp wiring across modules via a build-logic convention plugin (worker-kmp does not ship one — see the page for why)
• 📱 Platform setup: Android · iOS · Desktop · Web
• 🛠️ Features: Foreground Tasks · Telemetry / Observers · Web Push Server
• 🔒 Security · Performance
• 📦 Release process

License

Apache 2.0. © MobileByteLabs.