Forem: SuriDevs

R8 optimizedResourceShrinking: Reduce Android APK Size by 50%

SuriDevs — Mon, 30 Mar 2026 10:15:28 +0000

Resource shrinking has been around forever, but it's always been... okay. You enable it, you get some size reduction, but there's always unused stuff that slips through.

Android Gradle Plugin 8.12 changes this. Google integrated resource shrinking directly into R8's optimization pipeline, and the results are noticeably better.

What is Android Resource Shrinking?

Android apps have two types of bloat: code and resources. They need different tools to clean up.

Code shrinking (R8/ProGuard) removes unused Kotlin/Java classes, methods, and fields from your compiled code. If you wrote a utility class but never call it, R8 strips it out.

Resource shrinking removes unused drawables, layouts, strings, and other XML/binary resources from the final APK. That splash screen you deleted from code but forgot to remove from res/drawable? Resource shrinking catches it.

The key insight: these two are connected. Dead code might reference resources, and unused resources might only exist because dead code references them. When you optimize them separately, both miss things. That's exactly what optimizedResourceShrinking fixes — it runs both in the same pipeline.

How R8 optimizedResourceShrinking Works

The traditional flow looked like this:

AAPT2 compiles resources and generates keep rules
R8 shrinks and optimizes code
Resource shrinking runs as a separate post-processing step

The problem: AAPT2's keep rules were unconditional. It couldn't know which resources R8 would determine are unreachable. So it kept everything that might be used.

With optimizedResourceShrinking, R8 handles both in a single pass:

R8 analyzes code reachability (which classes/methods are actually called)
Simultaneously, it builds a resource reference graph (which resources are referenced by reachable code)
Resources only referenced by dead code get removed along with that dead code

This means R8 can see the full picture. If a feature flag disables a module at compile time, both the module's code AND its resources get stripped.

Why the Old Approach Leaked Resources

Traditional resource shrinking worked as a separate step from code optimization. AAPT2 would generate keep rules, R8 would do its thing, and then resource shrinking would run. The problem: those AAPT2 keep rules were unconditional.

This meant:

Code referencing unused resources stayed in the APK
Resources only used by dead code stayed too
Neither optimizer could see the full picture

The new approach runs both in the same R8 pipeline. Resources and code get analyzed together, so if code is dead, its resources go away too. And vice versa.

Enabling It

Add this to gradle.properties:

android.r8.optimizedResourceShrinking=true

You also need both minification and resource shrinking enabled in your release build:

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

That's it. Build your release APK and compare sizes.

What Kind of Reduction to Expect

Google claims 50%+ for apps with shared resources. In practice, it depends heavily on your app structure.

If you have a lot of library resources you don't use, or feature modules with resources only used in specific configurations, you'll see bigger gains. If your app is already lean and every resource is directly referenced, the improvement will be smaller.

Use APK Analyzer (Build → Analyze APK in Android Studio) to see where your size is actually coming from. Compare before and after - the res/ folder size should drop noticeably.

Watch Out For Dynamic Resource Loading

The biggest gotcha: resources loaded by string name at runtime.

// This will break - the optimizer can't see this reference
val resId = resources.getIdentifier("icon_$category", "drawable", packageName)

The optimizer doesn't know you're using those resources, so it removes them. Your app crashes with Resources$NotFoundException.

Fix it either by using direct references:

val resId = when(category) {
    "food" -> R.drawable.icon_food
    "travel" -> R.drawable.icon_travel
    else -> R.drawable.icon_default
}

Or by adding a keep file at res/raw/keep.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@drawable/icon_*" />

ProGuard Rules for Resources

If you need to keep specific resources that are referenced dynamically:

# Keep resources referenced by name at runtime
-keep class **.R$drawable {
    public static final int splash_logo;
    public static final int app_icon_*;
}

Testing Your Build

After enabling optimized shrinking:

Build a release APK
Install and test the app thoroughly
Pay special attention to features that load resources dynamically
Test on different device configurations (screen densities, languages)

If something breaks, check your dynamic resource loading first. Nine times out of ten, that's the issue.

Common Problems With Resource Shrinking

After enabling this on multiple projects, here are the issues I've hit:

1. Reflection-based resource access

Libraries that load resources by name at runtime will break. This is the most common issue. If you use a library that dynamically constructs resource names (like some icon packs or theme engines), you need to add keep rules.

2. Library resources you don't use

Third-party libraries bundle their own resources — icons, layouts, strings. With optimized shrinking, R8 is more aggressive about removing these. Occasionally a library accesses its own resources through reflection, and shrinking breaks it. The fix is usually a ProGuard keep rule from the library's documentation.

3. WebView HTML referencing Android resources

If your WebView loads local HTML that references file:///android_res/drawable/image.png, the shrinking won't see that reference. Those resources get removed and your WebView shows broken images. Move these assets to assets/ instead of res/.

4. Multi-module resource conflicts

In multi-module projects, resources with the same name in different modules can cause unexpected behavior when shrinking. Use resource prefixes (resourcePrefix "module_" in build.gradle) to avoid collisions.

Before and After: Real Numbers

Here's what I measured on our APK Manager app (https://www.suridevs.com/blog/posts/apk-manager-backup-restore-guide/) after enabling optimized shrinking:

Metric	Before	After
Total APK size	25.1 MB	13.2 MB
`res/` folder	14.8 MB	5.1 MB
`classes.dex`	6.2 MB	4.9 MB
Unused drawables removed	—	847
Unused strings removed	—	2,130

The biggest savings came from library resources we never used. Our app included Material Components, and the default theme bundles hundreds of drawables for widgets we never touch.

When It Becomes Default

Optimized resource shrinking is opt-in now, but it'll become the default in AGP 9.0.0. If you enable it now, you get ahead of any issues before you're forced to deal with them.

Is It Worth It?

For most apps, yes. The size reduction is real, and smaller APKs mean faster downloads and less storage pressure on user devices. The main cost is testing and potentially updating any dynamic resource loading patterns.

If you're distributing APKs directly (not through Play's AAB splitting), the savings are even more valuable since you're not getting per-device optimization anyway. For more on how APK packaging and split APKs work under the hood, see the Android PackageManager and ZIP64 APK guide at https://www.suridevs.com/blog/posts/apk-manager-backup-restore-guide/.

If you're building a Compose app and want to keep the overall architecture clean while optimizing, check out the MVVM Architecture guide at https://www.suridevs.com/blog/posts/mvvm-jetpack-compose-authentication-guide/.

Full technical details in Google's announcement.

Originally published at SuriDevs

Jetpack Compose Layouts: When to Use Row, Column, Box & ConstraintLayout

SuriDevs — Fri, 20 Mar 2026 05:52:14 +0000

Every time I start a new screen in Compose, I ask myself the same question: Row, Column, Box, or ConstraintLayout?

After building 40+ production screens across multiple apps, I've developed a pretty clear mental model for which layout to use when. The short version: Row, Column, and Box handle about 90% of what you'll ever need. ConstraintLayout fills the remaining 10% — but that 10% would be miserable without it.

Here's what I've learned.

Row, Column, Box — When to Use Each

These three are your workhorses. If you're coming from XML, think of them as replacements for LinearLayout(horizontal), LinearLayout(vertical), and FrameLayout.

Column — items stacked vertically. Use it for forms, lists of settings, card content, basically anything that reads top to bottom.

Column(modifier = Modifier.padding(16.dp)) {
    Text("Order #1234", style = MaterialTheme.typography.titleMedium)
    Spacer(modifier = Modifier.height(4.dp))
    Text("Placed on March 15, 2026", style = MaterialTheme.typography.bodySmall)
    Spacer(modifier = Modifier.height(12.dp))
    Text("3 items · $47.99", style = MaterialTheme.typography.bodyMedium)
}

Row — items laid out horizontally. Profile headers, action button groups, icon + text combos.

Row(
    modifier = Modifier.fillMaxWidth(),
    verticalAlignment = Alignment.CenterVertically
) {
    AsyncImage(
        model = user.avatarUrl,
        contentDescription = null,
        modifier = Modifier
            .size(48.dp)
            .clip(CircleShape)
    )
    Spacer(modifier = Modifier.width(12.dp))
    Column {
        Text(user.displayName, fontWeight = FontWeight.SemiBold)
        Text(user.role, style = MaterialTheme.typography.bodySmall)
    }
}

Box — items stacked on top of each other (z-axis). Overlays, badges, loading states on top of content.

Box(modifier = Modifier.fillMaxSize()) {
    LazyColumn { /* ... */ }

    FloatingActionButton(
        onClick = { /* ... */ },
        modifier = Modifier
            .align(Alignment.BottomEnd)
            .padding(16.dp)
    ) {
        Icon(Icons.Default.Add, contentDescription = "Add")
    }
}

My rule: if items go down the screen, Column. Side by side, Row. On top of each other, Box. You'd be surprised how far this gets you.

ConstraintLayout in Compose — When You Actually Need It

Here's the thing most tutorials don't tell you: you probably don't need ConstraintLayout in Compose.

In XML, ConstraintLayout solved a real problem — deeply nested LinearLayout and RelativeLayout trees that killed performance. But Compose's layout system is fundamentally different. Nesting Row inside Column inside Box doesn't create the same performance overhead because Compose uses a single-pass measurement system.

So when do I actually reach for ConstraintLayout in Compose?

1. Complex cross-references between siblings. When View A's position depends on View B's size, and View C needs to align with both.

2. Overlapping views with constraint-based positioning. Box handles simple overlaps, but when you need "this view's bottom aligns with that view's center, offset by 8dp" — that's constraint territory.

3. Barrier-based layouts. When you need a dynamic boundary that adjusts based on multiple views. There's no Row/Column equivalent for barriers.

4. Percentage-based positioning. Guidelines at 30% from the left, for example.

For everything else — and I mean the vast majority of screens — Row, Column, and Box are simpler, more readable, and perform the same.

Arrangement & Alignment

This confused me for weeks when I started with Compose. Here's the simple version:

Arrangement = how items are distributed along the main axis (horizontal for Row, vertical for Column).

Alignment = how items are positioned on the cross axis.

Row(
    modifier = Modifier.fillMaxWidth(),
    horizontalArrangement = Arrangement.SpaceEvenly,
    verticalAlignment = Alignment.CenterVertically
) {
    Icon(Icons.Default.Home, contentDescription = "Home")
    Icon(Icons.Default.Search, contentDescription = "Search")
    Icon(Icons.Default.Person, contentDescription = "Profile")
}

Arrangement.spacedBy() is the one I use 80% of the time. Fixed spacing between items. Clean and predictable.

Weight & Sizing

Weight in Compose works like layout_weight in XML's LinearLayout, but the API is cleaner:

Row(modifier = Modifier.fillMaxWidth()) {
    Text(
        text = product.name,
        modifier = Modifier.weight(0.7f),
        maxLines = 1,
        overflow = TextOverflow.Ellipsis
    )
    Text(
        text = product.price,
        modifier = Modifier.weight(0.3f),
        textAlign = TextAlign.End
    )
}

The gotcha I hit early on: weight is only available inside Row and Column scope. You can't use it inside Box.

Another pattern I use constantly — one item takes remaining space:

Row(
    modifier = Modifier.fillMaxWidth(),
    verticalAlignment = Alignment.CenterVertically
) {
    Text(
        text = "Settings",
        modifier = Modifier.weight(1f)
    )
    Switch(
        checked = isEnabled,
        onCheckedChange = { isEnabled = it }
    )
}

The weight(1f) on the text pushes the switch to the far right. No spacers needed.

Advanced Layouts with ConstraintLayout in Compose

When you do need ConstraintLayout, here's how the XML concepts translate.

Setup

dependencies {
    implementation("androidx.constraintlayout:constraintlayout-compose:1.1.1")
}

Chains

Link multiple composables for distribution:

ConstraintLayout(modifier = Modifier.fillMaxWidth()) {
    val (btn1, btn2, btn3) = createRefs()
    createHorizontalChain(btn1, btn2, btn3, chainStyle = ChainStyle.SpreadInside)

    Button(
        onClick = { },
        modifier = Modifier.constrainAs(btn1) {
            top.linkTo(parent.top)
        }
    ) { Text("Save") }

    Button(
        onClick = { },
        modifier = Modifier.constrainAs(btn2) {
            top.linkTo(parent.top)
        }
    ) { Text("Edit") }

    Button(
        onClick = { },
        modifier = Modifier.constrainAs(btn3) {
            top.linkTo(parent.top)
        }
    ) { Text("Delete") }
}

Guidelines

Invisible anchor lines at a percentage position:

ConstraintLayout(modifier = Modifier.fillMaxSize()) {
    val guideline = createGuidelineFromStart(fraction = 0.35f)
    val (image, content) = createRefs()

    Image(
        painter = painterResource(R.drawable.product),
        contentDescription = null,
        modifier = Modifier.constrainAs(image) {
            start.linkTo(parent.start)
            end.linkTo(guideline)
            width = Dimension.fillToConstraints
        }
    )

    Column(
        modifier = Modifier.constrainAs(content) {
            start.linkTo(guideline, margin = 12.dp)
            end.linkTo(parent.end)
            top.linkTo(parent.top)
            width = Dimension.fillToConstraints
        }
    ) {
        Text("Product Title", fontWeight = FontWeight.Bold)
        Text("Description goes here")
    }
}

Barriers

This is where ConstraintLayout genuinely shines — no Row/Column equivalent exists:

ConstraintLayout(modifier = Modifier.fillMaxWidth()) {
    val (label1, label2, input1, input2) = createRefs()
    val barrier = createEndBarrier(label1, label2)

    Text(
        text = "Name",
        modifier = Modifier.constrainAs(label1) {
            start.linkTo(parent.start)
            top.linkTo(parent.top)
        }
    )

    Text(
        text = "Email Address",
        modifier = Modifier.constrainAs(label2) {
            start.linkTo(parent.start)
            top.linkTo(label1.bottom, margin = 16.dp)
        }
    )

    OutlinedTextField(
        value = name,
        onValueChange = { name = it },
        modifier = Modifier.constrainAs(input1) {
            start.linkTo(barrier, margin = 12.dp)
            end.linkTo(parent.end)
            top.linkTo(label1.top)
            width = Dimension.fillToConstraints
        }
    )

    OutlinedTextField(
        value = email,
        onValueChange = { email = it },
        modifier = Modifier.constrainAs(input2) {
            start.linkTo(barrier, margin = 12.dp)
            end.linkTo(parent.end)
            top.linkTo(label2.top)
            width = Dimension.fillToConstraints
        }
    )
}

The barrier sits after whichever label is wider. Both input fields align perfectly regardless of label text length.

Real Example: Product Card

Here's a product card I built for an e-commerce app:

@Composable
fun ProductCard(product: Product, onAddToCart: () -> Unit) {
    ConstraintLayout(
        modifier = Modifier
            .fillMaxWidth()
            .padding(12.dp)
    ) {
        val (image, title, price, originalPrice, badge, cartBtn) = createRefs()

        AsyncImage(
            model = product.imageUrl,
            contentDescription = product.name,
            modifier = Modifier
                .constrainAs(image) {
                    top.linkTo(parent.top)
                    start.linkTo(parent.start)
                    end.linkTo(parent.end)
                    width = Dimension.fillToConstraints
                }
                .aspectRatio(1f)
                .clip(RoundedCornerShape(8.dp)),
            contentScale = ContentScale.Crop
        )

        if (product.discountPercent > 0) {
            Text(
                text = "-${product.discountPercent}%",
                color = Color.White,
                fontSize = 12.sp,
                fontWeight = FontWeight.Bold,
                modifier = Modifier
                    .constrainAs(badge) {
                        top.linkTo(image.top, margin = 8.dp)
                        end.linkTo(image.end, margin = 8.dp)
                    }
                    .background(Color(0xFFE53935), RoundedCornerShape(4.dp))
                    .padding(horizontal = 6.dp, vertical = 2.dp)
            )
        }

        Text(
            text = product.name,
            fontWeight = FontWeight.SemiBold,
            maxLines = 2,
            overflow = TextOverflow.Ellipsis,
            modifier = Modifier.constrainAs(title) {
                top.linkTo(image.bottom, margin = 8.dp)
                start.linkTo(parent.start)
                end.linkTo(parent.end)
                width = Dimension.fillToConstraints
            }
        )

        Text(
            text = "$${product.salePrice}",
            fontWeight = FontWeight.Bold,
            fontSize = 18.sp,
            modifier = Modifier.constrainAs(price) {
                top.linkTo(title.bottom, margin = 6.dp)
                start.linkTo(parent.start)
            }
        )

        Text(
            text = "$${product.originalPrice}",
            textDecoration = TextDecoration.LineThrough,
            color = MaterialTheme.colorScheme.onSurfaceVariant,
            fontSize = 14.sp,
            modifier = Modifier.constrainAs(originalPrice) {
                baseline.linkTo(price.baseline)
                start.linkTo(price.end, margin = 8.dp)
            }
        )

        IconButton(
            onClick = onAddToCart,
            modifier = Modifier.constrainAs(cartBtn) {
                top.linkTo(price.top)
                bottom.linkTo(price.bottom)
                end.linkTo(parent.end)
            }
        ) {
            Icon(Icons.Default.ShoppingCart, contentDescription = "Add to cart")
        }
    }
}

The baseline alignment between sale price and original price, the badge overlapping the image corner, and the cart button vertically centered against the price — all of that would need multiple nested Box/Row/Column combos.

Common Mistakes

1. Using ConstraintLayout when Row/Column works fine

A simple vertical form doesn't need constraints:

// Overkill
ConstraintLayout {
    val (title, subtitle, button) = createRefs()
    // ...12 lines of constraint wiring for 3 views in a column
}

// Better
Column(modifier = Modifier.padding(16.dp)) {
    Text("Title")
    Text("Subtitle")
    Button(onClick = { }) { Text("Submit") }
}

2. Forgetting Dimension.fillToConstraints

In ConstraintLayout, if you want a view to fill the space between its start and end constraints, you need width = Dimension.fillToConstraints. Without it, the view wraps its content.

3. Nesting Row inside Row inside Column

Three levels of nesting in Compose is a code smell. Step back and consider extracting a composable function or using ConstraintLayout.

4. Hardcoding sizes instead of using weight

// Fragile
Row {
    Text(modifier = Modifier.width(250.dp))
    Button(modifier = Modifier.width(100.dp))
}

// Responsive
Row {
    Text(modifier = Modifier.weight(1f))
    Button(onClick = { }) { Text("Go") }
}

5. Using fillMaxWidth() inside a weighted Row

If a child already has weight, adding fillMaxWidth() does nothing — weight already determines the width.

Performance: Nested vs Flat in Compose

Here's the thing XML developers need to unlearn: nesting in Compose is not the same performance problem as nesting in XML.

XML's LinearLayout inside LinearLayout caused exponential measure/layout passes. Compose's layout system enforces a single-pass measurement. Each composable is measured exactly once.

My guidelines:

1-2 levels of nesting: totally fine
3 levels: consider extracting composables
4+ levels: refactor — either extract or consider ConstraintLayout

I've never profiled a Compose app and found that layout nesting was the bottleneck. If your app is slow, look at recomposition count, image loading, and list performance first.

Quick Decision Guide

Need to stack items vertically?          → Column
Need items side by side?                 → Row
Need to overlay items?                   → Box
Need cross-references between siblings?  → ConstraintLayout
Need barrier-based alignment?            → ConstraintLayout
Need percentage positioning?             → ConstraintLayout
Building a form with aligned labels?     → ConstraintLayout
Everything else?                         → Row + Column + Box

Start simple. Add complexity only when the simpler approach gets awkward.

For setting up navigation between your layout screens, check out the Jetpack Compose Navigation tutorial at https://www.suridevs.com/blog/posts/navigation-component-jetpack-compose-complete-guide/. And if you're structuring ViewModels behind these screens, the MVVM Architecture guide at https://www.suridevs.com/blog/posts/mvvm-jetpack-compose-authentication-guide/ covers the patterns I use in production.

Originally published at SuriDevs

Jetpack Navigation 3 Migration: Type-Safe Routes & Nav2

SuriDevs — Thu, 19 Mar 2026 01:59:09 +0000

I have a production app with four bottom tabs, nine navigation graphs, and 40+ screens. Deep links from push notifications. OAuth callbacks from third-party services. Shared ViewModels across multi-screen flows.

Navigation 2 handled all of this. Messily, with string routes and withArgs hacks, but it worked.

Then I tried migrating to Navigation 3.

The first screen took 20 minutes. The bottom navigation took three days. Deep links? I almost gave up.

Nav3 is genuinely better -- type-safe routes, a visible back stack you actually control, no more NavController black box. But the migration path has gaps that the docs don't warn you about. Shared ViewModels work differently. Deep links are now your problem. Returning results between screens has no built-in solution.

This is everything I learned migrating a production app. The good parts, the painful parts, and the workarounds I wish someone had written down before I started.

What Nav3 Actually Changes

If you've been using Navigation 2, here's the mental shift:

Back stack ownership:
Nav2 — NavController manages everything behind a black box.
Nav3 — You own a SnapshotStateList back stack. Fully visible, fully yours.

Route definitions:
Nav2 — String routes: "project_detail/{projectId}/{projectName}"
Nav3 — Data classes: ProjectDetail(projectId = 42L, projectName = "Alpha")

Screen registration:
Nav2 — NavHost + composable() DSL
Nav3 — NavDisplay + entryProvider

Argument types:
Nav2 — navArgument(type = NavType.LongType)
Nav3 — Just... a Long property on a data class

Reading arguments:
Nav2 — backStackEntry.arguments?.getLong("projectId")
Nav3 — key.projectId

Navigation calls:
Nav2 — navController.navigate(route) / navController.popBackStack()
Nav3 — backStack.add(route) / backStack.removeLastOrNull()

The argument passing alone made the migration worth it. Take a screen that needs a project ID and name. The Nav2 route looked like this:

// Nav2: string route with arguments
"project_detail/{projectId}/{projectName}"

Two navArgument declarations. Two backStackEntry.arguments?.getXxx() calls. One wrong type and you get a runtime crash with an unhelpful error message.

Nav3 equivalent:

// Nav3: just a data class
@Serializable
data class ProjectDetail(
    val projectId: Long,
    val projectName: String
) : NavKey

Compile-time safe. IDE autocomplete. No parsing.

Setting Up Nav3

Dependencies

# gradle/libs.versions.toml

[versions]
nav3 = "1.0.1"
lifecycleNav3 = "2.10.0-rc01"

[libraries]
androidx-navigation3-runtime = { module = "androidx.navigation3:navigation3-runtime", version.ref = "nav3" }
androidx-navigation3-ui = { module = "androidx.navigation3:navigation3-ui", version.ref = "nav3" }
androidx-lifecycle-viewmodel-nav3 = { module = "androidx.lifecycle:lifecycle-viewmodel-navigation3", version.ref = "lifecycleNav3" }

// app/build.gradle.kts
dependencies {
    implementation(libs.androidx.navigation3.runtime)
    implementation(libs.androidx.navigation3.ui)
    implementation(libs.androidx.lifecycle.viewmodel.nav3)
}

You also need compileSdk = 36 and minSdk = 23. The minSdk bump from 21 caught me off guard -- I had to drop Android 4.x support. Check your analytics first.

Define Your Routes

Every route is now a @Serializable class implementing NavKey. No more string constants.

// navigation/Routes.kt

import androidx.navigation3.runtime.NavKey
import kotlinx.serialization.Serializable

// ---- Bottom tabs ----
@Serializable data object HomeTab : NavKey
@Serializable data object ProjectsTab : NavKey
@Serializable data object MessagesTab : NavKey
@Serializable data object SettingsTab : NavKey

// ---- Auth ----
@Serializable data object Welcome : NavKey
@Serializable data object Login : NavKey
@Serializable data class VerifyOtp(val email: String, val token: String) : NavKey

// ---- Projects ----
@Serializable data class ProjectDetail(
    val projectId: Long,
    val projectName: String
) : NavKey
@Serializable data class TaskDetail(
    val taskId: Long,
    val taskTitle: String,
    val projectId: Long
) : NavKey

Bottom Navigation with Multiple Back Stacks

This is where Nav3 gets interesting -- and where I spent three days.

In Nav2, each bottom tab's back stack was managed invisibly by NavController with saveState/restoreState. In Nav3, you manage each tab's back stack explicitly.

The Navigation State

class AppNavigationState(
    val startTab: NavKey,
    private val _currentTab: MutableState<NavKey>,
    val tabStacks: Map<NavKey, NavBackStack<NavKey>>
) {
    var currentTab: NavKey
        get() = _currentTab.value
        set(value) { _currentTab.value = value }

    val activeStacks: List<NavKey>
        get() = if (currentTab == startTab) {
            listOf(startTab)
        } else {
            listOf(startTab, currentTab)
        }
}

@Composable
fun rememberAppNavigationState(
    startTab: NavKey = HomeTab,
    tabs: Set<NavKey> = setOf(HomeTab, ProjectsTab, MessagesTab, SettingsTab)
): AppNavigationState {
    val currentTab = rememberSaveable { mutableStateOf(startTab) }
    val tabStacks = tabs.associateWith { tab -> rememberNavBackStack(tab) }

    return remember(startTab, tabs) {
        AppNavigationState(
            startTab = startTab,
            _currentTab = currentTab,
            tabStacks = tabStacks
        )
    }
}

The Navigator

class AppNavigator(private val state: AppNavigationState) {

    fun navigateTo(route: NavKey) {
        if (route in state.tabStacks.keys) {
            state.currentTab = route
        } else {
            state.tabStacks[state.currentTab]?.add(route)
        }
    }

    fun goBack(): Boolean {
        val currentStack = state.tabStacks[state.currentTab] ?: return false
        val currentRoute = currentStack.lastOrNull() ?: return false

        // At root of non-start tab? Go back to start tab
        if (currentRoute == state.currentTab && state.currentTab != state.startTab) {
            state.currentTab = state.startTab
            return true
        }

        // At root of start tab? Let the system handle it (exit app)
        if (currentRoute == state.startTab) {
            return false
        }

        currentStack.removeLastOrNull()
        return true
    }

    fun switchTab(tab: NavKey) {
        state.currentTab = tab
    }
}

The Hard Parts (And Workarounds)

1. Deep Links Are Now Your Problem

Nav2 had navDeepLink { uriPattern = "myapp://projects/{projectId}" }. Nav3 has nothing built in. You parse intents yourself and push routes onto the back stack.

object DeepLinkHandler {

    fun handleIntent(intent: Intent, navigator: AppNavigator): Boolean {
        val uri = intent.data ?: return false

        return when {
            uri.pathSegments.firstOrNull() == "projects" -> {
                val projectId = uri.pathSegments.getOrNull(1)?.toLongOrNull() ?: return false
                val projectName = uri.getQueryParameter("name") ?: "Unknown"

                navigator.switchTab(ProjectsTab)
                navigator.navigateTo(ProjectDetail(projectId = projectId, projectName = projectName))
                true
            }
            else -> false
        }
    }
}

2. Returning Results Between Screens

Nav2 had previousBackStackEntry?.savedStateHandle. Nav3 doesn't. Here's the pattern I use:

// 1. Define a result holder
class SelectMemberResult {
    var selectedMemberId: Long? by mutableStateOf(null)
}

// 2. Provide it via CompositionLocal
val LocalSelectMemberResult = staticCompositionLocalOf { SelectMemberResult() }

// 3. In the picker screen, set the result and go back
entry<SelectMemberForTeam> {
    val result = LocalSelectMemberResult.current
    SelectMemberScreen(
        onMemberSelected = { memberId ->
            result.selectedMemberId = memberId
            navigator.goBack()
        }
    )
}

3. Hilt ViewModels

Nav3 + Hilt works, but route arguments no longer appear in SavedStateHandle. You pass them manually:

// DON'T rely on SavedStateHandle for route args in Nav3:
@HiltViewModel
class ProjectDetailViewModel @Inject constructor(
    savedStateHandle: SavedStateHandle  // Empty! No route args here
) : ViewModel()

// DO pass the key directly:
entry<ProjectDetail> { key ->
    val viewModel: ProjectDetailViewModel = hiltViewModel()
    LaunchedEffect(key) {
        viewModel.initialize(key.projectId, key.projectName)
    }
    ProjectDetailScreen(viewModel = viewModel, onBack = { navigator.goBack() })
}

4. Screen Transition Animations

Nav3 has built-in support for transitions, including predictive back gesture animations.

NavDisplay(
    entries = entries,
    onBack = { navigator.goBack() },
    transitionSpec = {
        slideIntoContainer(AnimatedContentTransitionScope.SlideDirection.Start) togetherWith
            slideOutOfContainer(AnimatedContentTransitionScope.SlideDirection.Start)
    },
    popTransitionSpec = {
        slideIntoContainer(AnimatedContentTransitionScope.SlideDirection.End) togetherWith
            slideOutOfContainer(AnimatedContentTransitionScope.SlideDirection.End)
    }
)

Predictive back -- where the previous screen peeks as you swipe -- works out of the box.

The Migration Checklist

If you're migrating from Nav2, here's the order that worked for me:

Add Nav3 dependencies alongside Nav2 -- they don't conflict
Convert route definitions to @Serializable + NavKey data classes
Build NavigationState and Navigator for your bottom tabs
Migrate one tab at a time -- start with the simplest one
Move deep link handling to your own DeepLinkHandler
Convert result-passing screens to CompositionLocal pattern
Remove Nav2 dependencies after all screens are migrated
Test predictive back on every screen

Quick Reference

Nav2                              Nav3
────────────────────────────────────────────────────────
NavHost { }                   →   NavDisplay(entries, onBack)
composable<Route> { }         →   entry<Route> { key -> }
navController.navigate(r)     →   backStack.add(r)
navController.popBackStack()  →   backStack.removeLastOrNull()
NavType.LongType              →   just a Long property
navDeepLink { }               →   manual intent parsing
savedStateHandle result       →   CompositionLocal or shared flow
navigation<Parent> { }       →   gone (use entry decorators)

When NOT to Migrate

Don't migrate if:

Your app uses Fragments or Views -- Nav3 is Compose-only
You depend heavily on nested graph scoping -- still rough in Nav3
You need deep links handled by the framework -- you'll write that yourself
Your team is mid-sprint -- budget a week for 40 screens

Do migrate if:

You're starting a new Compose project
You're tired of runtime crashes from wrong argument types
You want predictive back gestures without extra work
You want to actually see your back stack

Wrapping Up

Nav3 is what Navigation for Compose should have been from the start. The back stack is yours. The routes are type-safe. Arguments are just properties.

For new projects, use Nav3. For existing apps, migrate when you have the bandwidth -- it's worth it, but budget a week, not an afternoon.

For the Nav2 approach with type-safe routes, popUpTo, and nested graphs, check out the Jetpack Compose Navigation tutorial at https://www.suridevs.com/blog/posts/navigation-component-jetpack-compose-complete-guide/. For structuring your ViewModels behind these screens, see the MVVM Architecture guide at https://www.suridevs.com/blog/posts/mvvm-jetpack-compose-authentication-guide/.

Originally published at SuriDevs

Jetpack Compose Navigation Tutorial: Type-Safe Routes & popUpTo

SuriDevs — Mon, 16 Mar 2026 06:17:00 +0000

I'll be honest - navigation in Android has always been a pain. Fragment transactions, back stack bugs, losing state when rotating the screen... I've spent countless hours debugging navigation issues over the years.

When I started using Navigation Component with Jetpack Compose, things got better. Not perfect (we'll get to the gotchas), but definitely better. After implementing navigation across multiple production apps, I wanted to share what actually works - and what doesn't.

Jetpack Compose Navigation Setup

Before anything else, add the navigation-compose dependency to your module-level build.gradle.kts:

dependencies {
    implementation("androidx.navigation:navigation-compose:2.8.9")
}

If you're using version catalogs (libs.versions.toml):

[versions]
navigationCompose = "2.8.9"

[libraries]
androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigationCompose" }

Then in your build.gradle.kts:

dependencies {
    implementation(libs.androidx.navigation.compose)
}

Sync your project, and you're ready to go. The examples below all use this single dependency.

The Problem with String-Based Routes

If you've worked with Navigation Compose before, you've probably written something like this:

navController.navigate("profile_screen/$userId")

Looks fine, right? Until you typo it as "profil_screen/$userId" somewhere and spend 20 minutes wondering why your app crashes. Ask me how I know.

The fix? Stop using raw strings. I use a sealed class approach that catches these mistakes at compile time:

sealed class AppRoute(val route: String) {
    companion object {
        const val AUTH_GRAPH_PATH = "auth_graph"
        const val MAIN_GRAPH_PATH = "main_graph"
    }

    data object AuthGraph : AppRoute(AUTH_GRAPH_PATH)
    data object MainGraph : AppRoute(MAIN_GRAPH_PATH)

    data object SignIn : AppRoute("$AUTH_GRAPH_PATH/sign_in_screen") {
        const val referralSource = "referralSource"
    }

    data object VerifyCode : AppRoute("$AUTH_GRAPH_PATH/verify_code_screen") {
        const val userEmail = "userEmail"
        const val expirySeconds = "expirySeconds"
    }

    data object Dashboard : AppRoute("$MAIN_GRAPH_PATH/dashboard_screen")
    data object UserProfile : AppRoute("$MAIN_GRAPH_PATH/profile_screen")

    fun withArgs(vararg args: Any?): String {
        return buildString {
            append(route)
            args.forEach { append("/$it") }
        }
    }

    fun withArgsFormat(vararg args: String?): String {
        return buildString {
            append(route)
            args.forEach { append("/{$it}") }
        }
    }
}

Now instead of navController.navigate("profile_screen/$userId"), I write navController.navigate(AppRoute.UserProfile.withArgs(userId)). Typo? Compiler yells at me. Problem solved before it reaches production.

Quick tip: Keep all your routes in a single file. When you have 50+ screens, you'll thank yourself for not having to hunt through the codebase to find route definitions.

Bottom Navigation That Actually Works

Bottom navigation sounds simple until you implement it. The first time I built it, tapping between tabs kept adding screens to the back stack. Users would hit back 15 times trying to exit the app. Embarrassing.

Here's the setup I use now:

sealed class BottomNavItem(
    val route: String,
    @StringRes val labelResId: Int,
    @DrawableRes val iconSelected: Int,
    @DrawableRes val iconUnselected: Int
) {
    data object Home : BottomNavItem(
        route = AppRoute.Dashboard.route,
        labelResId = R.string.tab_home,
        iconSelected = R.drawable.ic_home_filled,
        iconUnselected = R.drawable.ic_home_outline
    )

    data object Search : BottomNavItem(
        route = AppRoute.Search.route,
        labelResId = R.string.tab_search,
        iconSelected = R.drawable.ic_search_filled,
        iconUnselected = R.drawable.ic_search_outline
    )

    data object Favorites : BottomNavItem(
        route = AppRoute.Favorites.route,
        labelResId = R.string.tab_favorites,
        iconSelected = R.drawable.ic_favorite_filled,
        iconUnselected = R.drawable.ic_favorite_outline
    )

    data object Settings : BottomNavItem(
        route = AppRoute.Settings.route,
        labelResId = R.string.tab_settings,
        iconSelected = R.drawable.ic_settings_filled,
        iconUnselected = R.drawable.ic_settings_outline
    )

    companion object {
        val items = listOf(Home, Search, Favorites, Settings)
    }
}

And the actual navigation bar:

@Composable
fun AppBottomBar(
    navController: NavController,
    currentTabIndex: Int,
    onTabSelected: (Int) -> Unit
) {
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .background(MaterialTheme.colorScheme.surface)
            .padding(vertical = 8.dp),
        horizontalArrangement = Arrangement.SpaceEvenly
    ) {
        BottomNavItem.items.forEachIndexed { index, item ->
            val isSelected = currentTabIndex == index

            Box(
                modifier = Modifier
                    .weight(1f)
                    .clickable {
                        onTabSelected(index)
                        navController.navigate(item.route) {
                            popUpTo(navController.graph.findStartDestination().id) {
                                saveState = true
                            }
                            launchSingleTop = true
                            restoreState = true
                        }
                    },
                contentAlignment = Alignment.Center
            ) {
                Column(horizontalAlignment = Alignment.CenterHorizontally) {
                    Icon(
                        painter = painterResource(
                            if (isSelected) item.iconSelected else item.iconUnselected
                        ),
                        contentDescription = stringResource(item.labelResId),
                        tint = if (isSelected)
                            MaterialTheme.colorScheme.primary
                        else
                            MaterialTheme.colorScheme.onSurfaceVariant
                    )

                    if (isSelected) {
                        Text(
                            text = stringResource(item.labelResId),
                            style = MaterialTheme.typography.labelSmall,
                            color = MaterialTheme.colorScheme.primary
                        )
                    }
                }
            }
        }
    }
}

The three flags in the navigate block are crucial - I learned this the hard way:

popUpTo(startDestination) + saveState = true - Without this, every tab switch adds to the back stack AND you lose scroll position
launchSingleTop = true - Prevents duplicate screens when users spam-tap a tab
restoreState = true - Brings back the tab's previous state

Miss any of these and you'll get bug reports. Trust me.

Nested Graphs (How I Organize Large Apps)

When your app grows beyond 10-15 screens, throwing everything into one NavHost becomes a mess. I split navigation by feature:

// Auth module owns its own navigation
fun NavGraphBuilder.authNavGraph(
    navController: NavHostController,
    onAuthComplete: () -> Unit
) {
    navigation(
        route = AppRoute.AuthGraph.route,
        startDestination = AppRoute.Welcome.withArgsFormat(
            AppRoute.Welcome.referralSource
        )
    ) {
        addWelcomeScreen(navController)
        addSignInScreen(navController, onAuthComplete)
        addSignUpScreen(navController)
        addVerifyCodeScreen(navController)
        addResetPasswordScreen(navController, onAuthComplete)
        addForgotPasswordScreen(navController)
    }
}

// Main app module
fun NavGraphBuilder.mainNavGraph(
    navController: NavHostController,
    onSignOut: () -> Unit
) {
    navigation(
        route = AppRoute.MainGraph.route,
        startDestination = AppRoute.Dashboard.route
    ) {
        addDashboardScreen(navController)
        addHomeGraph(navController)
        addSearchGraph(navController)
        addFavoritesGraph(navController)
        addSettingsGraph(navController, onSignOut)
        addDetailsGraph(navController)
        addProfileGraph(navController)
    }
}

Then wire them together:

@Composable
fun RootNavigation(
    navController: NavHostController = rememberNavController(),
    startDestination: String = AppRoute.AuthGraph.route
) {
    NavHost(
        navController = navController,
        startDestination = startDestination
    ) {
        authNavGraph(
            navController = navController,
            onAuthComplete = {
                navController.navigate(AppRoute.MainGraph.route) {
                    popUpTo(AppRoute.AuthGraph.route) { inclusive = true }
                }
            }
        )

        mainNavGraph(
            navController = navController,
            onSignOut = {
                navController.navigate(AppRoute.AuthGraph.route) {
                    popUpTo(AppRoute.MainGraph.route) { inclusive = true }
                }
            }
        )
    }
}

Why I prefer this: Each feature team can work on their navigation independently. The auth team doesn't need to know anything about the settings flow, and vice versa. For how I structure the ViewModel and state management layer behind these screens, check out the MVVM Architecture guide at https://www.suridevs.com/blog/posts/mvvm-jetpack-compose-authentication-guide/.

Adding Screen Transitions

Default navigation has no animations - screens just pop in and out. It feels cheap. I add slide + fade transitions to everything:

private fun NavGraphBuilder.addSignInScreen(
    navController: NavHostController,
    onAuthComplete: () -> Unit
) {
    composable(
        route = AppRoute.SignIn.withArgsFormat(AppRoute.SignIn.referralSource),
        arguments = listOf(
            navArgument(AppRoute.SignIn.referralSource) {
                type = NavType.IntType
                defaultValue = -1
            }
        ),
        enterTransition = {
            slideInHorizontally { it } + fadeIn(tween(400))
        },
        exitTransition = {
            slideOutHorizontally { -it } + fadeOut(tween(400))
        },
        popEnterTransition = {
            slideInHorizontally { -it } + fadeIn(tween(400))
        },
        popExitTransition = {
            slideOutHorizontally { it } + fadeOut(tween(400))
        }
    ) { backStackEntry ->
        val referralSource = backStackEntry.arguments
            ?.getInt(AppRoute.SignIn.referralSource)

        SignInScreen(
            referralSource = referralSource,
            onNavigateBack = { navController.navigateUp() },
            onForgotPassword = {
                navController.navigate(
                    AppRoute.ForgotPassword.withArgs(referralSource)
                )
            },
            onSignUp = {
                navController.navigate(
                    AppRoute.SignUp.withArgs(referralSource)
                )
            },
            onSignInSuccess = onAuthComplete
        )
    }
}

400ms feels right to me - fast enough to not annoy users, slow enough to actually see the transition. I tried 300ms initially but it felt too abrupt.

Gotcha: Don't forget popEnterTransition and popExitTransition. Without them, going back looks weird because the animations don't reverse properly.

Passing Multiple Arguments (The Ugly Part)

This is where Navigation Component gets annoying. Passing one or two arguments is fine. But what about six?

navController.navigate(
    AppRoute.VerifyCode.withArgs(
        userEmail,
        expirySeconds,
        sourceId,
        sessionToken,
        null,  // optional param
        originScreen
    )
)

Yeah, it's a lot of boilerplate. Some people use SafeArgs or custom serialization to clean this up. The newer Navigation 3 API (https://www.suridevs.com/blog/posts/navigation-3-jetpack-compose-migration-guide/) eliminates most of this with type-safe serialization, but if you're on Nav2, I've just accepted the verbosity - it works and it's explicit about what's being passed.

Important: If you're passing complex objects, don't. Pass IDs and fetch the data in the destination screen. Navigation arguments are meant for primitives and simple strings.

Architecture Overview

Here's roughly how the navigation structure looks when everything is connected:

┌─────────────────────────────────────────────────────────┐
│                     MainActivity                        │
│                          │                              │
│                      NavHost                            │
│          ┌───────────────┴───────────────┐              │
│          ▼                               ▼              │
│     AuthGraph                       MainGraph           │
│     ├── Welcome                     ├── Dashboard       │
│     ├── SignIn                      │   ├── HomeGraph   │
│     ├── SignUp                      │   ├── SearchGraph │
│     ├── VerifyCode                  │   ├── Favorites   │
│     ├── ForgotPassword              │   └── Settings    │
│     └── CreatePassword              ├── DetailsGraph    │
│                                     └── ProfileGraph    │
└─────────────────────────────────────────────────────────┘

Deep Linking

If you need to open specific screens from push notifications or external links, add deep links to your composable:

composable(
    route = AppRoute.ItemDetail.withArgsFormat(AppRoute.ItemDetail.itemId),
    arguments = listOf(
        navArgument(AppRoute.ItemDetail.itemId) { type = NavType.StringType }
    ),
    deepLinks = listOf(
        navDeepLink {
            uriPattern = "https://example.com/item/{${AppRoute.ItemDetail.itemId}}"
        },
        navDeepLink {
            uriPattern = "myapp://item/{${AppRoute.ItemDetail.itemId}}"
        }
    )
) { backStackEntry ->
    ItemDetailScreen(
        itemId = backStackEntry.arguments?.getString(AppRoute.ItemDetail.itemId)
    )
}

Don't forget to add the intent filter in your manifest. I've seen people set up deep links in code and wonder why they don't work - the manifest configuration is easy to miss.

Common Mistakes I've Made (So You Don't Have To)

1. Forgetting inclusive = true when clearing back stack

After login, you want to clear the auth screens so users can't go back to them:

navController.navigate(AppRoute.MainGraph.route) {
    popUpTo(AppRoute.AuthGraph.route) { inclusive = true }  // Don't forget this!
}

Without inclusive = true, the Welcome screen stays in the back stack.

2. Not handling configuration changes

If you store navController in a regular variable instead of using rememberNavController(), you'll lose navigation state on rotation.

3. Navigating from non-UI threads

Navigation must happen on the main thread. If you're navigating after an API call, make sure you're on the right dispatcher.

4. Passing large objects as arguments

Just don't. Pass an ID, fetch the data in the destination. I learned this when my app started crashing with TransactionTooLargeException.

Wrapping Up

Navigation Component isn't perfect, but it beats manual Fragment transactions any day. The sealed class approach for routes has saved me from countless typos, and proper back stack handling makes the app feel polished.

If you're starting a new Compose project, set up your navigation structure early. Retrofitting this into an existing app is painful - I've done it twice and don't recommend it.

If you're evaluating whether Compose is the right choice for your project, I wrote about the strengths and weaknesses of Jetpack Compose (https://www.suridevs.com/blog/posts/jetpack-compose-strengths-weaknesses/) from a production perspective. And if you're ready to move to the latest navigation API, check out the Navigation 3 migration guide at https://www.suridevs.com/blog/posts/navigation-3-jetpack-compose-migration-guide/.

Originally published at SuriDevs

Kotlin Coroutines: From Callback Hell to Clean Async Code

SuriDevs — Fri, 13 Mar 2026 05:09:21 +0000

I spent years writing callback-based Android code. Nested callbacks inside callbacks, trying to chain API calls, handling errors at every level. It worked, but reading that code six months later was painful. Coroutines changed that completely.

If you're still on callbacks or RxJava and wondering if coroutines are worth learning - they are. Not because they're new and shiny, but because they make async code look like regular sequential code. That's it. That's the whole pitch.

The Problem Coroutines Solve

Here's what loading data looked like with callbacks in a document scanner app I worked on:

// The callback nightmare - actual pattern from production code
fun processScannedDocument(bitmap: Bitmap) {
    imageProcessor.detectEdges(bitmap, object : Callback<EdgeResult> {
        override fun onSuccess(edges: EdgeResult) {
            imageProcessor.cropToEdges(bitmap, edges, object : Callback<Bitmap> {
                override fun onSuccess(cropped: Bitmap) {
                    imageProcessor.enhanceContrast(cropped, object : Callback<Bitmap> {
                        override fun onSuccess(enhanced: Bitmap) {
                            ocrEngine.extractText(enhanced, object : Callback<String> {
                                override fun onSuccess(text: String) {
                                    runOnUiThread {
                                        showResult(enhanced, text)
                                    }
                                }
                                override fun onError(e: Exception) {
                                    runOnUiThread { showError(e) }
                                }
                            })
                        }
                        override fun onError(e: Exception) {
                            runOnUiThread { showError(e) }
                        }
                    })
                }
                override fun onError(e: Exception) {
                    runOnUiThread { showError(e) }
                }
            })
        }
        override fun onError(e: Exception) {
            runOnUiThread { showError(e) }
        }
    })
}

Four levels deep. Each callback needs its own error handling. The actual business logic - detect edges, crop, enhance, OCR - is buried in ceremony.

Here's the same thing with coroutines:

suspend fun processScannedDocument(bitmap: Bitmap): DocumentResult {
    return try {
        val edges = imageProcessor.detectEdges(bitmap)
        val cropped = imageProcessor.cropToEdges(bitmap, edges)
        val enhanced = imageProcessor.enhanceContrast(cropped)
        val text = ocrEngine.extractText(enhanced)
        DocumentResult.Success(enhanced, text)
    } catch (e: Exception) {
        DocumentResult.Error(e.message ?: "Processing failed")
    }
}

Sequential code that happens to be async. One try-catch handles all errors. The processing pipeline is obvious at a glance.

Suspend Functions - The Building Block

The suspend keyword marks functions that can pause and resume. When you call a suspend function, it doesn't block the thread - it suspends execution, frees the thread for other work, and resumes when the result is ready.

// This doesn't block the main thread
suspend fun calculateExpenseSplit(
    participants: List<Participant>,
    items: List<ExpenseItem>
): SplitResult {
    return withContext(Dispatchers.Default) {
        // Complex calculation happens off main thread
        val individualShares = mutableMapOf<String, Double>()

        items.forEach { item ->
            val sharers = item.sharedBy
            val perPersonCost = item.amount / sharers.size
            sharers.forEach { sharerId ->
                individualShares[sharerId] =
                    (individualShares[sharerId] ?: 0.0) + perPersonCost
            }
        }

        SplitResult(individualShares, calculateSettlements(individualShares))
    }
}

You can only call suspend functions from other suspend functions or from a coroutine scope. The compiler enforces this - try calling a suspend function from a regular function and you'll get an error.

Dispatchers - Where Your Code Runs

This confused me at first. Dispatchers determine which thread pool your coroutine uses:

Dispatchers.Main - The UI thread. Use for updating views, showing dialogs. Never do heavy work here.

Dispatchers.IO - Optimized for blocking IO operations. Network calls, file reads, database queries. Can spin up more threads than CPU cores because these operations spend most time waiting.

Dispatchers.Default - CPU-intensive work. Image processing, complex calculations, parsing large data. Thread count matches CPU cores.

Here's how I use them in a podcast app:

class EpisodeDownloader @Inject constructor(
    private val api: PodcastApi,
    private val storage: EpisodeStorage
) {
    suspend fun downloadEpisode(episode: Episode): DownloadResult {
        return withContext(Dispatchers.IO) {
            try {
                // Download audio file
                val audioBytes = api.downloadAudio(episode.audioUrl)

                // Save to local storage
                val localPath = storage.saveAudioFile(episode.id, audioBytes)

                // Update database
                storage.markAsDownloaded(episode.id, localPath)

                DownloadResult.Success(localPath)
            } catch (e: Exception) {
                DownloadResult.Error(e.message ?: "Download failed")
            }
        }
    }

    suspend fun transcribeEpisode(audioPath: String): String {
        return withContext(Dispatchers.Default) {
            // CPU-heavy transcription work
            transcriptionEngine.processAudio(audioPath)
        }
    }
}

The withContext block switches to the specified dispatcher, does the work, and automatically switches back when done. No manual thread management.

Structured Concurrency - Why It Matters

This feature saves you from memory leaks. Every coroutine runs inside a scope, and when that scope is cancelled, all coroutines inside it get cancelled too.

In Android, you typically use these scopes:

viewModelScope - Tied to ViewModel lifecycle. Cancelled when ViewModel is cleared.

lifecycleScope - Tied to Activity/Fragment lifecycle. Cancelled when destroyed.

class ParkingFinderViewModel @Inject constructor(
    private val parkingRepository: ParkingRepository,
    private val locationProvider: LocationProvider
) : ViewModel() {

    private val _parkingState = MutableStateFlow<ParkingState>(ParkingState.Idle)
    val parkingState: StateFlow<ParkingState> = _parkingState.asStateFlow()

    fun findNearbyParking() {
        // This coroutine automatically cancels if ViewModel is cleared
        viewModelScope.launch {
            _parkingState.value = ParkingState.Searching

            try {
                val location = locationProvider.getCurrentLocation()
                val spots = parkingRepository.findAvailableSpots(
                    latitude = location.latitude,
                    longitude = location.longitude,
                    radiusMeters = 500
                )
                _parkingState.value = ParkingState.Found(spots)
            } catch (e: Exception) {
                _parkingState.value = ParkingState.Error(
                    e.message ?: "Failed to find parking"
                )
            }
        }
    }
}

User navigates away, ViewModel gets cleared, coroutine gets cancelled. No stale location updates, no memory leaks from holding references to destroyed activities.

Parallel Execution with async/await

Sometimes you need multiple things at once. A pet care app might need to load pet profile, upcoming vet appointments, and feeding schedule - all from different sources.

Sequential approach (slow):

// Takes ~3 seconds (1 + 1 + 1)
suspend fun loadPetDashboard(petId: String): PetDashboard {
    val profile = petRepository.getProfile(petId)          // 1 second
    val appointments = vetRepository.getUpcoming(petId)    // 1 second
    val feedingSchedule = scheduleRepository.get(petId)    // 1 second
    return PetDashboard(profile, appointments, feedingSchedule)
}

Parallel approach (fast):

// Takes ~1 second (all run simultaneously)
suspend fun loadPetDashboard(petId: String): PetDashboard = coroutineScope {
    val profile = async { petRepository.getProfile(petId) }
    val appointments = async { vetRepository.getUpcoming(petId) }
    val feedingSchedule = async { scheduleRepository.get(petId) }

    PetDashboard(
        profile = profile.await(),
        appointments = appointments.await(),
        feedingSchedule = feedingSchedule.await()
    )
}

async starts a coroutine that returns a Deferred - basically a promise. await() suspends until the result is ready. The three calls run simultaneously, so total time is the slowest one, not the sum.

That coroutineScope wrapper is important. If any of the async calls fail, it cancels the others and throws the exception. Without it, you might have orphaned coroutines still running after an error.

Exception Handling

Coroutine exception handling has some quirks that bit me early on.

For launch, uncaught exceptions propagate to the parent scope:

viewModelScope.launch {
    throw RuntimeException("Boom")  // Crashes the app
}

For async, exceptions are held until you call await():

viewModelScope.launch {
    val deferred = async { throw RuntimeException("Boom") }
    // Exception thrown here when await() is called
    deferred.await()
}

I always wrap coroutine bodies in try-catch for any operation that can fail:

viewModelScope.launch {
    try {
        val result = riskyOperation()
        handleSuccess(result)
    } catch (e: CancellationException) {
        // Don't catch cancellation - rethrow it
        throw e
    } catch (e: Exception) {
        handleError(e)
    }
}

That CancellationException check is critical. Coroutine cancellation works by throwing CancellationException. If you catch and swallow it, your coroutine won't actually cancel. Always rethrow it.

Timeouts

External services hang sometimes. Users hate waiting forever. Use withTimeout to set limits:

suspend fun checkParkingAvailability(spotId: String): AvailabilityStatus {
    return try {
        withTimeout(5000) {  // 5 seconds max
            parkingApi.checkRealTimeStatus(spotId)
        }
    } catch (e: TimeoutCancellationException) {
        AvailabilityStatus.Unknown  // Fallback on timeout
    }
}

Or withTimeoutOrNull for a cleaner null fallback:

suspend fun checkParkingAvailability(spotId: String): AvailabilityStatus {
    return withTimeoutOrNull(5000) {
        parkingApi.checkRealTimeStatus(spotId)
    } ?: AvailabilityStatus.Unknown
}

I use 10-15 second timeouts for network calls and 30 seconds for file operations. Anything longer and users have already given up.

Flow for Streams of Data

suspend functions return one value. Flow returns multiple values over time - like tracking a delivery or monitoring plant sensor data.

// In repository - emits location updates for a delivery
fun trackDelivery(orderId: String): Flow<DeliveryLocation> = flow {
    while (currentCoroutineContext().isActive) {
        val location = deliveryApi.getCurrentLocation(orderId)
        emit(location)

        if (location.status == DeliveryStatus.DELIVERED) {
            break
        }

        delay(10_000)  // Check every 10 seconds
    }
}

// In ViewModel
class DeliveryTrackingViewModel @Inject constructor(
    private val repository: DeliveryRepository
) : ViewModel() {

    private val _deliveryLocation = MutableStateFlow<DeliveryLocation?>(null)
    val deliveryLocation: StateFlow<DeliveryLocation?> = _deliveryLocation

    fun startTracking(orderId: String) {
        viewModelScope.launch {
            repository.trackDelivery(orderId)
                .catch { e ->
                    // Handle errors without crashing the flow
                    _deliveryLocation.value = null
                }
                .collect { location ->
                    _deliveryLocation.value = location
                }
        }
    }
}

The flow keeps emitting location updates until the delivery is complete or the scope is cancelled.

Cancellation - Making It Work Right

Coroutines are cancellable, but your code needs to cooperate. Long-running operations should check for cancellation:

suspend fun batchProcessPhotos(photos: List<PhotoUri>): List<ProcessedPhoto> {
    return photos.map { photo ->
        // Check if we should stop before processing each photo
        ensureActive()

        withContext(Dispatchers.Default) {
            val bitmap = loadBitmap(photo)
            val resized = resizeBitmap(bitmap, maxWidth = 1080)
            val compressed = compressToJpeg(resized, quality = 85)
            ProcessedPhoto(photo.id, compressed)
        }
    }
}

ensureActive() throws CancellationException if the coroutine was cancelled. Without it, your loop keeps running even after the user navigated away.

For CPU-heavy work, use yield() to give cancellation a chance:

suspend fun analyzeExpensePatterns(
    transactions: List<Transaction>
): SpendingAnalysis {
    return withContext(Dispatchers.Default) {
        val categories = mutableMapOf<String, Double>()

        transactions.forEach { transaction ->
            yield()  // Check for cancellation periodically

            val category = categorizeTransaction(transaction)
            categories[category] = (categories[category] ?: 0.0) + transaction.amount
        }

        SpendingAnalysis(categories, calculateTrends(categories))
    }
}

Testing Coroutines

One of the best things about coroutines - they're testable without waiting for real time. Use runTest from the coroutines test library:

class ParkingFinderViewModelTest {

    @Test
    fun `findNearbyParking updates state with spots on success`() = runTest {
        val fakeRepository = FakeParkingRepository()
        fakeRepository.setSpots(listOf(
            ParkingSpot("1", "Main St Garage", available = true),
            ParkingSpot("2", "Central Lot", available = true)
        ))
        val fakeLocation = FakeLocationProvider(lat = 37.7749, lng = -122.4194)

        val viewModel = ParkingFinderViewModel(fakeRepository, fakeLocation)
        viewModel.findNearbyParking()

        // runTest automatically advances virtual time
        val state = viewModel.parkingState.value
        assertTrue(state is ParkingState.Found)
        assertEquals(2, (state as ParkingState.Found).spots.size)
    }

    @Test
    fun `findNearbyParking shows error when location unavailable`() = runTest {
        val fakeRepository = FakeParkingRepository()
        val fakeLocation = FakeLocationProvider(shouldFail = true)

        val viewModel = ParkingFinderViewModel(fakeRepository, fakeLocation)
        viewModel.findNearbyParking()

        assertTrue(viewModel.parkingState.value is ParkingState.Error)
    }
}

runTest handles virtual time - delays complete instantly, timeouts work correctly, and you don't wait for real time to pass.

Mistakes I Made So You Don't Have To

Using GlobalScope - Just don't. It's not tied to any lifecycle, so those coroutines run forever. Memory leaks guaranteed.

// Don't do this
GlobalScope.launch {
    syncPetData()
}

// Do this instead
viewModelScope.launch {
    syncPetData()
}

Blocking the Main Thread - runBlocking blocks the current thread until complete. On Main thread, that freezes your UI.

// This freezes the UI
fun onScanButtonClick() {
    runBlocking {
        processDocument(bitmap)  // UI frozen until complete
    }
}

// This doesn't
fun onScanButtonClick() {
    viewModelScope.launch {
        processDocument(bitmap)  // UI stays responsive
    }
}

Forgetting withContext for Heavy Work - If you're doing CPU or IO work without specifying a dispatcher, you might be running it on Main.

// This runs on Main thread - blocks UI!
viewModelScope.launch {
    val enhanced = imageProcessor.enhance(bitmap)  // Heavy work on Main
}

// This is correct
viewModelScope.launch {
    val enhanced = withContext(Dispatchers.Default) {
        imageProcessor.enhance(bitmap)
    }
}

Catching CancellationException - If you catch all exceptions, you're breaking cancellation.

// Broken cancellation
try {
    downloadEpisode(episode)
} catch (e: Exception) {
    // CancellationException caught and swallowed - coroutine won't cancel!
    log(e)
}

// Correct
try {
    downloadEpisode(episode)
} catch (e: CancellationException) {
    throw e  // Always rethrow
} catch (e: Exception) {
    log(e)
}

Creating New Scopes Inside Coroutines - This breaks structured concurrency.

// Bad - orphaned scope, not cancelled with parent
viewModelScope.launch {
    CoroutineScope(Dispatchers.IO).launch {
        riskyOperation()  // Keeps running even if viewModel cleared
    }
}

// Good - child coroutine, cancelled with parent
viewModelScope.launch {
    withContext(Dispatchers.IO) {
        riskyOperation()
    }
}

When Not to Use Coroutines

Coroutines aren't always the answer:

Simple synchronous code - If it's not async, don't make it async. Adding coroutines to code that doesn't need them just adds complexity.

One-shot callbacks from libraries - A single callback from a third-party library is fine. You can wrap it with suspendCoroutine, but sometimes the effort isn't worth it for a single call.

When the team doesn't know them - If nobody on the team understands coroutines, introducing them in a critical feature is risky. Train first, then adopt.

Wrapping Up

Coroutines took me a few weeks to really internalize. The mental shift from callbacks to sequential async code was the hardest part. Once that clicked, everything else followed.

Start small - convert one callback-heavy function to suspend and see how it feels. Then gradually expand. The patterns here - dispatchers, structured concurrency, exception handling, cancellation - cover most of what you'll need in production.

The code is cleaner, easier to test, and most importantly, easier to understand when you come back to it months later. That alone makes coroutines worth the learning curve.

From Foreground Services to WorkManager: How We Cut Battery Drain by 70%

SuriDevs — Thu, 12 Mar 2026 04:51:38 +0000

40% of my users on Android 14 were crashing. Every. Single. Day.

The crash logs all said the same thing: ForegroundServiceStartNotAllowedException. My auto backup service that had worked fine for four years just... stopped working. Google had finally won the war against background services, and I was collateral damage.

The Old Way Worked Great (Until It Didn't)

Our All Backup & Restore app (2M+ downloads) had a simple approach since 2020: start a foreground service on boot, listen for app installs, backup immediately. Users loved the "real-time" feel.

class BootCompleteReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        if (intent?.action == "android.intent.action.BOOT_COMPLETED") {
            context?.startForegroundService(serviceIntent)
        }
    }
}

The service would show a persistent notification, register broadcast receivers for PACKAGE_ADDED and PACKAGE_REPLACED, and backup any new app within seconds.

Then the complaints started rolling in.

Death by a Thousand Paper Cuts

First came the battery complaints. "Why is there always a notification?" "App drains battery even when I'm not using it." Fair points, but the app needed to run constantly to catch installs. Trade-offs, right?

Then Android 14 landed and everything broke.

Fatal Exception: ForegroundServiceStartNotAllowedException
Unable to start service - not allowed to start foreground service

I added FOREGROUND_SERVICE_TYPE_DATA_SYNC. Still crashed. Added the new permissions. Still crashed. Added restart logic when the system killed the service.

Still. Crashed.

I spent two weeks fighting this. Samsung phones killed the service. Xiaomi's "battery optimization" murdered it. OnePlus had its own special way of breaking things. Every manufacturer had custom restrictions, and my service was losing the fight on all fronts.

The Moment I Gave Up (In a Good Way)

Mid-2025. I was looking at production data:

Significant portion of Android 14 users experiencing service crashes
Noticeable battery consumption from the background service
User retention dropping - people were uninstalling

I'd been fighting the platform for months. Maybe it was time to stop.

The realization hit me: real-time backup detection was a nice-to-have, not a must-have. Did users actually need their apps backed up within seconds of installation? Or would an hour delay be totally fine?

Spoiler: an hour delay was totally fine.

Polling Instead of Listening

The new approach is embarrassingly simple. Instead of running a service 24/7 listening for broadcasts, I just... check every hour if anything changed.

val workRequest = PeriodicWorkRequestBuilder<MonitorWorker>(
    1, TimeUnit.HOURS
)
.setConstraints(
    Constraints.Builder()
        .setRequiresBatteryNotLow(true)
        .setRequiresStorageNotLow(true)
        .build()
)
.build()

WorkManager.getInstance(context)
    .enqueueUniquePeriodicWork(
        "app_monitor_work",
        ExistingPeriodicWorkPolicy.KEEP,
        workRequest
    )

The MonitorWorker wakes up, compares the current installed apps against a saved list, detects any new or updated apps, and schedules backup workers for them. Then it goes back to sleep. No persistent notification. No fighting the system.

The Change Detection Logic

fun detectChanges(lastKnown: List<AppInfo>, current: List<AppInfo>): List<AppInfo> {
    val changes = mutableListOf<AppInfo>()
    val lastKnownMap = lastKnown.associateBy { it.packageName }

    for (app in current) {
        val oldApp = lastKnownMap[app.packageName]
        when {
            oldApp == null -> changes.add(app.copy(isNew = true))
            app.versionCode > oldApp.versionCode -> changes.add(app.copy(isUpdate = true))
        }
    }
    return changes
}

I store the app list in SharedPreferences (serialized with Kotlin Serialization). Every hour, load the old list, get current apps from PackageManager, compare, save the new list. Simple.

The 20-App Update Incident

Two weeks after shipping the WorkManager version, I got ANR reports. Turns out Google Play sometimes updates 20+ apps at once (usually after a fresh install or when the phone was off for a while). My code was scheduling 20 backup workers simultaneously.

The fix was dumb but effective - stagger the workers:

changedApps.forEachIndexed { index, app ->
    val delaySeconds = index * 20L
    // App 0: immediate, App 1: 20s, App 2: 40s, etc.
    scheduleBackup(app, delaySeconds)
}

Now at most 1-2 workers run concurrently. ANRs gone.

That Weird Coroutine Bug

I had a subtle bug that took forever to track down. Some backups would just... fail silently. The worker reported success, but the backup didn't exist.

The culprit:

// This was the problem
fun saveBundleApp() = CoroutineScope(Dispatchers.IO).async {
    // Orphaned scope - not connected to parent lifecycle
}

When WorkManager cancelled the worker, this orphaned coroutine kept running... for about 2 seconds before it got garbage collected. The fix:

// This works properly
suspend fun saveBundleApp(): Result = coroutineScope {
    try {
        val result = async { /* backup logic */ }.await()
        result
    } catch (e: Exception) {
        Result.failure(e)
    }
}

Structured concurrency exists for a reason. I learned that reason the hard way.

What Changed for Users

Before (Foreground Service):

Battery drain: Noticeable daily impact
Persistent notification: Always there, always annoying
Backup delay: Immediate (0-5 seconds)
Crashes on Android 14: Constant
App store rating: Trending down

After (WorkManager):

Battery drain: ~70% reduction
Notification: Only during active backup
Backup delay: Up to 1 hour (nobody complained)
Crashes: 95% reduction
Rating: Stabilized, battery complaints stopped

What I Wish I'd Known Earlier

The "real-time" requirement was in my head, not in user feedback. I assumed people needed instant backups. They didn't. They just wanted backups to happen automatically at some point. An hour delay? Nobody noticed.

Polling feels wrong to programmers. "Why check every hour when you could just listen for events?" Because listening requires running constantly, and Android doesn't want you running constantly. Polling wakes up, does work, goes to sleep. Android likes that.

WorkManager constraints are underrated. Setting setRequiresBatteryNotLow(true) means my workers don't run when the phone is dying. Users never see "this backup app drained my battery" in low-battery situations because... the app isn't running in low-battery situations.

Test on real phones from real manufacturers. Emulators don't have Samsung's "battery optimization" or Xiaomi's "battery saver" or OnePlus's "deep sleep mode." These features murder background processes in creative ways. If it works on the emulator but fails on a real Samsung phone, the Samsung phone is the ground truth.

If You're Still Using Foreground Services

Ask yourself: does this genuinely need to run 24/7? Or did I just build it that way because broadcast receivers were easy?

The migration pattern is straightforward:

Save your state to persistent storage
Schedule a periodic WorkManager worker
On each run, compare current state to saved state
Process any changes
Save the new state
Sleep

Add constraints so you don't run during low battery or low storage. Stagger work if you might have bursts of activity. Use structured concurrency.

The platform has made its stance clear: efficient apps get to run, inefficient apps get killed. WorkManager is the peace treaty between your app and the system. Sign it.

I spent months fighting Android's background restrictions. Then I spent two weeks implementing WorkManager and wondering why I hadn't done it sooner. The app is more stable, uses less battery, and I'm not debugging manufacturer-specific foreground service murders anymore.

Sometimes the right answer isn't working harder. It's working with the system instead of against it.