shekhar23/claude-zero-to-hero-android-kmp/android-workmanager

Android WorkManager

When to Use It

Use WorkManager for work that is:

• deferrable
• guaranteed eventually
• expected to continue across app restarts or process death
• constrained by network, charging, battery, or storage conditions

Do not use WorkManager for:

• immediate in-app UI actions
• work that must finish while the screen is visible only
• exact alarms
• long-running foreground media playback

Core Principles

• Workers must be idempotent — safe to run more than once.
• Prefer unique work so duplicate jobs do not pile up.
• Keep business logic in domain/data classes; the worker only coordinates execution.
• Return Result.retry() only for failures that may succeed later.
• Pass IDs and lightweight flags through Data, not large payloads.

Worker Structure

Use CoroutineWorker for suspending APIs:

class SyncNotesWorker(
    appContext: Context,
    params: WorkerParameters,
    private val noteRepository: NoteRepository
) : CoroutineWorker(appContext, params) {
 
    override suspend fun doWork(): Result {
        return when (noteRepository.sync()) {
            is com.example.core.domain.Result.Success -> Result.success()
            is com.example.core.domain.Result.Error -> Result.retry()
        }
    }
}

Map typed domain/data failures to WorkManager results intentionally:

• temporary network failure -> Result.retry()
• invalid input or permanent server rejection -> Result.failure()
• success -> Result.success()

Unique One-Time Work

Prefer enqueueUniqueWork(...) for user-triggered syncs:

workManager.enqueueUniqueWork(
    "sync-notes",
    ExistingWorkPolicy.KEEP,
    OneTimeWorkRequestBuilder<SyncNotesWorker>()
        .setConstraints(syncConstraints())
        .build()
)

Use:

• KEEP when an existing in-flight job should continue
• REPLACE when the newest request should win
• APPEND only for true chains that must run in sequence

Periodic Work

Use periodic work for recurring sync or cleanup:

workManager.enqueueUniquePeriodicWork(
    "periodic-note-sync",
    ExistingPeriodicWorkPolicy.KEEP,
    PeriodicWorkRequestBuilder<SyncNotesWorker>(12, TimeUnit.HOURS)
        .setConstraints(syncConstraints())
        .build()
)

Periodic work is inexact. Do not use it for exact-time requirements.

Constraints

Create reusable constraint builders:

fun syncConstraints(): Constraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresBatteryNotLow(true)
    .build()

Common defaults:

• uploads/sync -> network connected
• expensive maintenance -> charging + idle if appropriate
• local cleanup -> no network needed

Avoid over-constraining work or it may never run.

Retry and Backoff

When retrying, define backoff explicitly:

OneTimeWorkRequestBuilder<SyncNotesWorker>()
    .setBackoffCriteria(
        BackoffPolicy.EXPONENTIAL,
        30,
        TimeUnit.SECONDS
    )
    .build()

Use retry only for transient failures like:

• no internet
• 5xx server responses
• temporary rate limits

Do not retry validation failures, missing required IDs, or unsupported states.

Chaining Work

Chain work when steps are strictly sequential:

workManager
    .beginUniqueWork("export-notes", ExistingWorkPolicy.REPLACE, exportRequest)
    .then(uploadRequest)
    .enqueue()

Each step should still be independently safe and idempotent.

Input and Output Data

Keep Data small and primitive:

val request = OneTimeWorkRequestBuilder<UploadAttachmentWorker>()
    .setInputData(workDataOf("attachmentId" to attachmentId))
    .build()

Pass IDs, not serialized objects or file blobs.

Observing Work State

Expose work status to presentation through a repository or small observer abstraction:

fun observeSyncWork(): Flow<WorkInfo?> {
    return workManager.getWorkInfosForUniqueWorkFlow("sync-notes")
        .map { infos -> infos.firstOrNull() }
}

The ViewModel maps WorkInfo.State into UI state like isSyncing, lastSyncFailed, or lastSyncAt.

Dependency Injection

If the app uses Koin, register workers in DI and configure the app-level WorkManager factory once. Keep worker constructors thin and inject repositories/use cases instead of service locators.

Checklist: Adding Background Work

• [ ] Confirm the use case really needs WorkManager
• [ ] Make the worker idempotent
• [ ] Keep worker logic orchestration-only
• [ ] Use unique work for duplicate-prone jobs
• [ ] Add only necessary constraints
• [ ] Retry only transient failures
• [ ] Expose work status to the ViewModel if the UI needs it