Offline-first apps and DataStore

Why offline-first?

Mobile networks are unreliable: lifts, metro tunnels, villages with weak signal, expensive data packs. An app that shows a blank screen whenever the network is slow feels broken. An offline-first app always shows something useful immediately (the last saved data) and updates it when the network allows.

The pattern

UI  <-- observes --  Room (single source of truth)  <-- saves --  Network
 |                                                               ^
 +--------------- "refresh" event --> Repository ----------------+

class NewsRepository(private val api: NewsApi, private val dao: ArticleDao) {
    val articles: Flow<List<Article>> = dao.observeAll()      // the UI reads only this

    suspend fun refresh(): Result<Unit> = try {
        val fresh = api.latest().map { it.toEntity() }
        dao.upsertAll(fresh)                                  // the Flow emits the new list
        Result.success(Unit)
    } catch (e: IOException) {
        Result.failure(e)                                     // keep showing saved articles
    }
}

Room's @Upsert inserts new rows and updates existing ones in one call, which is handy for saving fresh network data. Because the screen observes the database Flow, it updates automatically after the save.

When should the app refresh? Common choices: when a screen opens, on pull-to-refresh, and periodically in the background. Many apps also skip the refresh if the data is still fresh, for example saved less than five minutes ago, to save the user's data pack and battery.

Preferences DataStore for small settings

Some data is not a table: a dark-mode switch, the chosen language, "has seen onboarding". For these, Android recommends Jetpack DataStore. Preferences DataStore stores key-value pairs, works with coroutines and Flow, and is safe to use from any thread. It replaces the older SharedPreferences.

val Context.settingsStore by preferencesDataStore(name = "settings")
private val DARK_MODE = booleanPreferencesKey("dark_mode")

class SettingsRepository(private val context: Context) {
    val darkMode: Flow<Boolean> = context.settingsStore.data.map { it[DARK_MODE] ?: false }

    suspend fun setDarkMode(on: Boolean) {
        context.settingsStore.edit { it[DARK_MODE] = on }
    }
}

Background sync with WorkManager

Some work must happen even if the user closes the app: uploading a form filled offline, syncing every few hours. WorkManager is the Jetpack library for deferrable, guaranteed background work. You describe a Worker, add constraints such as "only on Wi-Fi" or "only when charging", and Android runs it at a suitable time, even after a reboot.

Common mistakes

• Showing network data directly and the database separately: two sources of truth that disagree.
• Using SharedPreferences for new code: prefer DataStore.
• Creating several DataStore instances for the same file: errors and corruption. Use one per file.
• Running sync in a plain coroutine that dies with the app. Use WorkManager for guaranteed work.