KMP WorkManager

Background task scheduling for Kotlin Multiplatform

Write once, run everywhere — Schedule background tasks on Android and iOS from shared code

Features • Installation • Quick Start • Documentation • Examples

Building a multiplatform app that needs background task scheduling?

// ❌ Platform-specific nightmare
expect class BackgroundScheduler {
    fun schedule(task: Task)
}

// Android implementation uses WorkManager
// iOS implementation uses BGTaskScheduler
// Different APIs, different behaviors, double the code

// ✅ One API, both platforms
val scheduler = BackgroundTaskScheduler()

scheduler.enqueue(
    id = "sync-data",
    trigger = TaskTrigger.Periodic(intervalMs = 900_000),
    workerClassName = "SyncWorker",
    constraints = Constraints(requiresNetwork = true)
)

No expect/actual. No platform checks. Just works.

Single API for Android WorkManager and iOS BGTaskScheduler. Write scheduling logic once in common code.

Sequential task execution with automatic state recovery. If interrupted, chains resume where they left off.

scheduler.beginWith(TaskRequest("Download"))
    .then(TaskRequest("Process"))
    .then(TaskRequest("Upload"))
    .enqueue()

• One-time: Execute once, optionally delayed
• Periodic: Run every N minutes (min 15min)
• Exact: Precise timing on Android via AlarmManager
• Chains: Multi-step workflows with state persistence

Ready-to-use workers for common tasks:

• HttpRequestWorker — Make HTTP calls
• HttpDownloadWorker — Download files
• HttpUploadWorker — Upload files
• HttpSyncWorker — Sync data
• FileCompressionWorker — Compress files

Built-in SSRF protection, input validation, and resource limits (v2.3.1+).

• 60-86% faster HTTP operations via singleton client (v2.3.4+)
• O(1) queue operations on iOS
• Efficient memory usage with streaming I/O

Workers return structured results with custom data (v2.3.0+):

override suspend fun doWork(input: String?): WorkerResult {
    val result = uploadFile()
    return WorkerResult.Success(
        message = "Upload complete",
        data = mapOf("fileSize" to result.size, "duration" to result.duration)
    )
}

Add to your build.gradle.kts:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("dev.brewkits:kmpworkmanager:2.3.4")
        }
    }
}

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        KmpWorkManager.initialize(
            context = this,
            config = KmpWorkManagerConfig(
                logLevel = Logger.Level.INFO
            )
        )
    }
}

// iosMain/MyWorkerFactory.kt
class MyWorkerFactory : IosWorkerFactory {
    override fun createWorker(workerClassName: String): IosWorker? {
        return when (workerClassName) {
            "DataSyncWorker" -> DataSyncWorkerIos()
            else -> null
        }
    }
}

// iOSApp.swift
import ComposeApp  // Your shared framework name

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    override init() {
        super.init()

        // Initialize Koin with worker factory
        KoinInitializerKt.doInitKoin(platformModule: IOSModuleKt.iosModule)
    }

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Register background task handlers
        registerBackgroundTasks()
        return true
    }

    private func registerBackgroundTasks() {
        // See platform-setup.md for full implementation
    }
}

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>kmp_chain_executor_task</string>
</array>

→ Full setup guide: Platform Setup Documentation

// commonMain
class DataSyncWorker : CommonWorker {
    override suspend fun doWork(input: String?): WorkerResult {
        val api = ApiClient()
        val data = api.fetchLatestData()

        database.save(data)

        return WorkerResult.Success(
            message = "Synced ${data.size} items",
            data = mapOf("count" to data.size)
        )
    }
}

Platform-specific implementations:

// androidMain
class DataSyncWorkerAndroid : AndroidWorker {
    override suspend fun doWork(input: String?): WorkerResult {
        return DataSyncWorker().doWork(input)
    }
}

// iosMain
class DataSyncWorkerIos : IosWorker {
    override suspend fun doWork(input: String?): WorkerResult {
        return DataSyncWorker().doWork(input)
    }
}

// In your shared code
val scheduler = BackgroundTaskScheduler()

scheduler.enqueue(
    id = "data-sync",
    trigger = TaskTrigger.Periodic(intervalMs = 900_000), // 15 minutes
    workerClassName = "DataSyncWorker",
    constraints = Constraints(
        requiresNetwork = true,
        requiresCharging = false
    )
)

The task will run every 15 minutes on both Android and iOS, only when network is available.

iOS Limitations:

• System decides when to run tasks (opportunistic scheduling)
• Force-quit cancels all pending tasks
• Execution may be delayed for hours
• Not suitable for time-critical operations

scheduler.enqueue(
    id = "sync",
    trigger = Periodic(15.minutes),
    constraints = Constraints(
        requiresNetwork = true,
        requiresCharging = false
    )
)

scheduler.enqueue(
    id = "upload",
    workerClassName = "UploadWorker",
    constraints = Constraints(
        requiresNetwork = true,
        requiresCharging = true
    )
)

scheduler.beginWith(
    TaskRequest("Download")
).then(
    TaskRequest("Process")
).then(
    TaskRequest("Upload")
).enqueue()

📘 Getting Started

• Quick Start Guide — Get running in 5 minutes
• Platform Setup — Android & iOS configuration
• Migration Guide — Upgrading from v2.3.3

📖 Core Concepts

• API Reference — Complete API documentation
• Task Chains — Sequential workflows
• Built-in Workers — Pre-built workers

🎯 Platform-Specific

• iOS Best Practices — iOS background task tips
• Android Configuration — Android setup details

Check the /composeApp directory for a complete demo app with:

• ✅ Single task scheduling
• ✅ Chain execution examples
• ✅ Built-in worker usage
• ✅ Error handling patterns
• ✅ Real device testing

🚀 Performance

• 60-86% faster HTTP operations (singleton HttpClient with connection pooling)
• 90% less progress data loss on iOS (reduced flush interval: 500ms → 100ms)

🐛 Fixes

• Fixed iOS queue compaction segmentation fault
• Fixed Logger test assertions
• Added proper shutdown mechanism for background operations

⚠️ Breaking Changes

• TaskChain.enqueue() is now suspending

→ Full changelog: CHANGELOG.md

→ Migration guide: MIGRATION_V2.3.3_TO_V2.3.4.md

Dependencies:

• AndroidX WorkManager (Android)
• Koin (Dependency Injection)
• Ktor (HTTP operations)
• kotlinx.coroutines
• kotlinx.serialization

┌─────────────────────────────────────┐
│     Common API (Multiplatform)      │
│   BackgroundTaskScheduler Interface │
└─────────────┬───────────────────────┘
              │
      ┌───────┴────────┐
      │                │
┌─────▼─────┐    ┌────▼─────┐
│  Android  │    │   iOS    │
│ WorkManager│    │BGTask    │
│            │    │Scheduler │
└────────────┘    └──────────┘

All scheduling logic lives in common code. Platform implementations handle OS-specific details transparently.

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Before submitting:

• Run tests: ./gradlew test
• Check code style: ./gradlew ktlintCheck
• Update documentation if needed

Copyright 2024-2026 Nguyễn Tuấn Việt

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

💬 Need help?

• 📖 Documentation
• 🐛 Report Issues
• 💡 Discussions
• 📧 Email: datacenter111@gmail.com

⭐ Like this project? Give it a star on GitHub!