Compose Patterns

State management patterns

State hoisting

Move state up to the caller so composables remain stateless and reusable.

// Stateless composable - receives state and events
@Composable
fun SearchBar(
    query: String,
    onQueryChange: (String) -> Unit,
    modifier: Modifier = Modifier,
) {
    TextField(
        value = query,
        onValueChange = onQueryChange,
        modifier = modifier,
        placeholder = { Text("Search...") },
    )
}

// Stateful wrapper - owns the state
@Composable
fun SearchBarStateful() {
    var query by remember { mutableStateOf("") }
    SearchBar(query = query, onQueryChange = { query = it })
}

UiState pattern

Model screen state as a single sealed interface or data class.

sealed interface ProductsUiState {
    data object Loading : ProductsUiState
    data class Success(val products: List<Product>) : ProductsUiState
    data class Error(val message: String) : ProductsUiState
}

@HiltViewModel
class ProductsViewModel @Inject constructor(
    private val repository: ProductRepository,
) : ViewModel() {
    val uiState: StateFlow<ProductsUiState> = repository.getProducts()
        .map<List<Product>, ProductsUiState> { ProductsUiState.Success(it) }
        .catch { emit(ProductsUiState.Error(it.message ?: "Unknown error")) }
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), ProductsUiState.Loading)
}

@Composable
fun ProductsScreen(viewModel: ProductsViewModel = hiltViewModel()) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    when (val state = uiState) {
        is ProductsUiState.Loading -> CircularProgressIndicator()
        is ProductsUiState.Success -> ProductList(state.products)
        is ProductsUiState.Error -> ErrorMessage(state.message)
    }
}

Derived state

Use derivedStateOf when one state value is computed from another to avoid unnecessary recompositions.

val items = remember { mutableStateListOf<Item>() }
val sortedItems by remember { derivedStateOf { items.sortedBy { it.name } } }

Recomposition optimization

Stability

Compose skips recomposition for composables whose parameters have not changed. For this to work, parameters must be stable (immutable data classes, primitives, or annotated with @Stable/@Immutable).

@Immutable
data class Product(
    val id: String,
    val name: String,
    val price: Double,
)

Lists are unstable by default. Wrap in an immutable holder:

@Immutable
data class ProductList(val items: List<Product>)

Key for LazyColumn

Always provide a key in LazyColumn/LazyRow to preserve state across reorderings.

LazyColumn {
    items(products, key = { it.id }) { product ->
        ProductCard(product)
    }
}

Material 3 theming

Dynamic color

@Composable
fun AppTheme(content: @Composable () -> Unit) {
    val colorScheme = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        val context = LocalContext.current
        if (isSystemInDarkTheme()) dynamicDarkColorScheme(context)
        else dynamicLightColorScheme(context)
    } else {
        if (isSystemInDarkTheme()) darkColorScheme() else lightColorScheme()
    }

    MaterialTheme(
        colorScheme = colorScheme,
        typography = Typography,
        content = content,
    )
}

Custom color scheme

private val LightColors = lightColorScheme(
    primary = Color(0xFF6750A4),
    onPrimary = Color.White,
    primaryContainer = Color(0xFFEADDFF),
    secondary = Color(0xFF625B71),
    background = Color(0xFFFFFBFE),
    surface = Color(0xFFFFFBFE),
)

Side effects

// Launch a one-time effect when the screen appears
LaunchedEffect(Unit) {
    viewModel.loadData()
}

// Clean up a listener
DisposableEffect(lifecycleOwner) {
    val observer = LifecycleEventObserver { _, event -> /* handle */ }
    lifecycleOwner.lifecycle.addObserver(observer)
    onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
}

Custom layouts

Use Layout composable for custom measurement and placement.

@Composable
fun FlowRow(
    modifier: Modifier = Modifier,
    spacing: Dp = 8.dp,
    content: @Composable () -> Unit,
) {
    Layout(content = content, modifier = modifier) { measurables, constraints ->
        val placeables = measurables.map { it.measure(constraints) }
        var x = 0
        var y = 0
        var rowHeight = 0

        layout(constraints.maxWidth, constraints.maxHeight) {
            placeables.forEach { placeable ->
                if (x + placeable.width > constraints.maxWidth) {
                    x = 0
                    y += rowHeight + spacing.roundToPx()
                    rowHeight = 0
                }
                placeable.placeRelative(x, y)
                x += placeable.width + spacing.roundToPx()
                rowHeight = maxOf(rowHeight, placeable.height)
            }
        }
    }
}

Prefer FlowRow and FlowColumn from androidx.compose.foundation.layout (available in Compose Foundation 1.4+) over custom implementations.

Coroutines and Flows

Coroutine scopes in Android

// ViewModel - preferred for most Android work
class MyViewModel : ViewModel() {
    init {
        viewModelScope.launch {
            // Automatically cancelled when ViewModel is cleared
        }
    }
}

// Compose event handler
@Composable
fun MyScreen() {
    val scope = rememberCoroutineScope()
    Button(onClick = {
        scope.launch { /* handle event */ }
    }) { Text("Click") }
}

Dispatchers

viewModelScope.launch {
    // On Main by default
    _uiState.update { it.copy(isLoading = true) }

    val result = withContext(Dispatchers.IO) {
        repository.fetchData()  // blocking I/O
    }

    // Back on Main
    _uiState.update { it.copy(data = result, isLoading = false) }
}

Flow types

Cold flows

Regular Flow is cold - it starts producing values only when collected.

fun getUsers(): Flow<List<User>> = flow {
    val users = api.fetchUsers()
    emit(users)
}

// Or from Room (already cold)
@Query("SELECT * FROM users")
fun getAll(): Flow<List<User>>

Hot flows (StateFlow and SharedFlow)

// StateFlow - always has a value, replays latest to new collectors
private val _uiState = MutableStateFlow(UiState())
val uiState: StateFlow<UiState> = _uiState.asStateFlow()

// SharedFlow - no initial value, configurable replay
private val _events = MutableSharedFlow<UiEvent>()
val events: SharedFlow<UiEvent> = _events.asSharedFlow()

Converting cold to hot

val uiState: StateFlow<UiState> = repository.getItems()
    .map { items -> UiState(items = items) }
    .stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5000),
        initialValue = UiState(),
    )

Use SharingStarted.WhileSubscribed(5000) (5 second timeout) to keep the upstream alive during configuration changes but stop it when truly not needed.

Flow operators

Common transformations

repository.getProducts()
    .map { products -> products.filter { it.inStock } }   // transform
    .distinctUntilChanged()                                 // skip duplicates
    .debounce(300)                                          // for search input
    .catch { emit(emptyList()) }                            // handle errors
    .onEach { analytics.logProductsLoaded(it.size) }       // side effect
    .flowOn(Dispatchers.Default)                            // change upstream dispatcher
    .collect { products -> /* use result */ }

Combining flows

// Combine latest values from multiple flows
val uiState: StateFlow<SearchUiState> = combine(
    searchQuery,
    repository.getProducts(),
    selectedCategory,
) { query, products, category ->
    val filtered = products
        .filter { it.category == category }
        .filter { it.name.contains(query, ignoreCase = true) }
    SearchUiState(results = filtered)
}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), SearchUiState())

// Zip - pairs elements one-to-one
flowA.zip(flowB) { a, b -> Pair(a, b) }

// FlatMapLatest - cancel previous inner flow when new value arrives
searchQuery.flatMapLatest { query ->
    repository.search(query)
}

Structured concurrency patterns

Parallel decomposition

viewModelScope.launch {
    // Run two operations in parallel
    coroutineScope {
        val user = async { userRepository.getUser(id) }
        val orders = async { orderRepository.getOrders(id) }
        _uiState.update {
            it.copy(user = user.await(), orders = orders.await())
        }
    }
}

SupervisorScope

Use when you want sibling coroutines to be independent (one failure doesn't cancel others).

viewModelScope.launch {
    supervisorScope {
        launch { syncUsers() }      // failure here won't cancel syncOrders
        launch { syncOrders() }     // failure here won't cancel syncUsers
    }
}

Error handling

In coroutines

viewModelScope.launch {
    try {
        val data = withContext(Dispatchers.IO) { api.fetchData() }
        _uiState.update { it.copy(data = data) }
    } catch (e: IOException) {
        _uiState.update { it.copy(error = "Network error: ${e.message}") }
    } catch (e: HttpException) {
        _uiState.update { it.copy(error = "Server error: ${e.code()}") }
    }
}

In flows

repository.getItems()
    .catch { e ->
        // Catch upstream errors, emit fallback
        emit(emptyList())
        _errors.emit("Failed to load: ${e.message}")
    }
    .collect { items -> /* use items */ }

catch only catches upstream errors. If the collect block throws, it propagates to the coroutine's exception handler.

CoroutineExceptionHandler

private val handler = CoroutineExceptionHandler { _, exception ->
    _uiState.update { it.copy(error = exception.message) }
}

viewModelScope.launch(handler) {
    riskyOperation()
}

Testing coroutines

Setup

@OptIn(ExperimentalCoroutinesApi::class)
class MyViewModelTest {
    private val testDispatcher = UnconfinedTestDispatcher()

    @Before
    fun setup() {
        Dispatchers.setMain(testDispatcher)
    }

    @After
    fun teardown() {
        Dispatchers.resetMain()
    }
}

Testing StateFlow

@Test
fun `loads products on init`() = runTest {
    val fakeRepo = FakeProductRepository(listOf(Product("1", "Widget")))
    val viewModel = ProductsViewModel(fakeRepo)

    val state = viewModel.uiState.first { it is ProductsUiState.Success }
    assertThat((state as ProductsUiState.Success).products).hasSize(1)
}

Turbine for Flow testing

// Add: testImplementation("app.cash.turbine:turbine:1.1.0")
@Test
fun `emits loading then success`() = runTest {
    viewModel.uiState.test {
        assertThat(awaitItem()).isEqualTo(ProductsUiState.Loading)
        assertThat(awaitItem()).isInstanceOf(ProductsUiState.Success::class.java)
        cancelAndConsumeRemainingEvents()
    }
}

Use UnconfinedTestDispatcher for tests where you want eager execution. Use StandardTestDispatcher when you need to control virtual time with advanceTimeBy() or advanceUntilIdle().

Play Store Release Checklist

Pre-release build checklist

1. Version management

// app/build.gradle.kts
android {
    defaultConfig {
        versionCode = 12          // Must increment every upload. Integer only.
        versionName = "2.3.0"     // User-visible. Follow semver.
    }
}

The Play Store rejects uploads where versionCode is not strictly greater than the previously uploaded version.

2. Release signing

android {
    signingConfigs {
        create("release") {
            storeFile = file(System.getenv("KEYSTORE_PATH") ?: "release.keystore")
            storePassword = System.getenv("KEYSTORE_PASSWORD") ?: ""
            keyAlias = System.getenv("KEY_ALIAS") ?: ""
            keyPassword = System.getenv("KEY_PASSWORD") ?: ""
        }
    }
    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
            isMinifyEnabled = true
            isShrinkResources = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro",
            )
        }
    }
}

Use Google Play App Signing (recommended). Upload your app signing key to Play Console and sign uploads with a separate upload key. If the upload key is compromised, Google can reset it without affecting end users.

3. Build the release AAB

./gradlew bundleRelease

# Output: app/build/outputs/bundle/release/app-release.aab

Always use AAB (Android App Bundle) instead of APK for Play Store. AAB enables Dynamic Delivery, reducing download size by 15-30%.

4. Test the release build locally

# Install release build on device
./gradlew installRelease

# Or use bundletool to test AAB locally
bundletool build-apks --bundle=app-release.aab --output=app.apks \
  --ks=release.keystore --ks-key-alias=key0
bundletool install-apks --apks=app.apks

ProGuard / R8 configuration

Common keep rules

# Kotlin serialization
-keepattributes *Annotation*, InnerClasses
-dontnote kotlinx.serialization.AnnotationsKt

-keepclassmembers class kotlinx.serialization.json.** {
    *** Companion;
}

# Retrofit
-keepattributes Signature, InnerClasses, EnclosingMethod
-keepattributes RuntimeVisibleAnnotations, RuntimeVisibleParameterAnnotations
-keepclassmembers,allowshrinking,allowobfuscation interface * {
    @retrofit2.http.* <methods>;
}

# Room
-keep class * extends androidx.room.RoomDatabase
-keep @androidx.room.Entity class *

# Gson (if used)
-keepattributes Signature
-keep class com.example.app.data.model.** { *; }

# Hilt
-keep class dagger.hilt.** { *; }
-keep class javax.inject.** { *; }
-keep @dagger.hilt.android.lifecycle.HiltViewModel class * { *; }

Debugging R8 issues

# Generate mapping file for crash deobfuscation
android {
    buildTypes {
        release {
            proguardFiles(...)
            // mapping.txt generated at build/outputs/mapping/release/mapping.txt
        }
    }
}

Upload mapping.txt to Play Console (App bundle explorer > Downloads tab) for deobfuscated crash reports in Android Vitals.

Store listing requirements

Required assets

Content rating

Complete the IARC content rating questionnaire in Play Console. Without it, the app may be removed from the store. Covers violence, sexual content, language, and other categories.

Privacy policy

Required for all apps that:

• Request sensitive permissions (camera, location, contacts, etc.)
• Access personal or sensitive user data
• Target children (COPPA compliance)

Host the privacy policy at a publicly accessible URL.

Data safety form

Declare all data collection and sharing practices. Required since July 2022. Categories include: name, email, location, photos, app activity, device IDs.

Release tracks

Staged rollout

Production release flow:
1. Upload AAB to production track
2. Set rollout percentage (start at 5-10%)
3. Monitor Android Vitals for 24-48 hours
4. Check crash rate, ANR rate, user feedback
5. Increase to 25% -> 50% -> 100%
6. Halt rollout immediately if crash rate exceeds baseline

A staged rollout to 5% for 48 hours catches most critical issues before they affect the full user base.

Android Vitals thresholds

Google penalizes apps in search ranking if they exceed these thresholds:

Reducing ANRs

• Never do I/O on the main thread
• Use StrictMode during development to detect violations
• Keep BroadcastReceiver.onReceive() under 10 seconds
• Use WorkManager for background tasks instead of long-running services

Reducing crashes

• Handle nullable data from APIs defensively
• Test on low-memory devices (use isLowRamDevice)
• Test with and without network connectivity
• Use ProcessLifecycleOwner to handle process death gracefully

CI/CD integration

GitHub Actions example

name: Release
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 17
      - name: Build release AAB
        run: ./gradlew bundleRelease
        env:
          KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
          KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
          KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
      - name: Upload to Play Store
        uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.PLAY_SERVICE_ACCOUNT }}
          packageName: com.example.app
          releaseFiles: app/build/outputs/bundle/release/app-release.aab
          track: internal
          mappingFile: app/build/outputs/mapping/release/mapping.txt

Store the keystore file as a base64-encoded secret, decode it in CI. Never commit keystores or credentials to version control.

Room Advanced

Type converters

Room only supports primitive types and strings natively. Use @TypeConverter for complex types.

class Converters {
    @TypeConverter
    fun fromTimestamp(value: Long?): Date? = value?.let { Date(it) }

    @TypeConverter
    fun dateToTimestamp(date: Date?): Long? = date?.time

    @TypeConverter
    fun fromStringList(value: String?): List<String> =
        value?.split(",")?.map { it.trim() } ?: emptyList()

    @TypeConverter
    fun stringListToString(list: List<String>): String = list.joinToString(",")
}

@Database(entities = [Task::class], version = 1)
@TypeConverters(Converters::class)
abstract class AppDatabase : RoomDatabase() {
    abstract fun taskDao(): TaskDao
}

For complex objects, prefer storing as JSON with a Gson/Moshi converter. For lists of IDs, consider a junction table instead of serialized strings.

Relations

One-to-many

@Entity
data class User(
    @PrimaryKey val userId: Long,
    val name: String,
)

@Entity(
    foreignKeys = [ForeignKey(
        entity = User::class,
        parentColumns = ["userId"],
        childColumns = ["ownerUserId"],
        onDelete = ForeignKey.CASCADE,
    )]
)
data class Playlist(
    @PrimaryKey val playlistId: Long,
    val ownerUserId: Long,
    val name: String,
)

data class UserWithPlaylists(
    @Embedded val user: User,
    @Relation(parentColumn = "userId", entityColumn = "ownerUserId")
    val playlists: List<Playlist>,
)

@Dao
interface UserDao {
    @Transaction
    @Query("SELECT * FROM User WHERE userId = :id")
    fun getUserWithPlaylists(id: Long): Flow<UserWithPlaylists>
}

Always annotate relation queries with @Transaction to ensure data consistency across the multiple queries Room executes internally.

Many-to-many

@Entity(primaryKeys = ["playlistId", "songId"])
data class PlaylistSongCrossRef(
    val playlistId: Long,
    val songId: Long,
)

data class PlaylistWithSongs(
    @Embedded val playlist: Playlist,
    @Relation(
        parentColumn = "playlistId",
        entityColumn = "songId",
        associateBy = Junction(PlaylistSongCrossRef::class),
    )
    val songs: List<Song>,
)

Complex queries

Dynamic queries with RawQuery

@Dao
interface SearchDao {
    @RawQuery(observedEntities = [Task::class])
    fun search(query: SupportSQLiteQuery): Flow<List<Task>>
}

// Usage
val query = SimpleSQLiteQuery(
    "SELECT * FROM tasks WHERE title LIKE ? ORDER BY createdAt DESC",
    arrayOf("%$searchTerm%"),
)
searchDao.search(query)

Full-text search (FTS4)

@Fts4(contentEntity = Task::class)
@Entity(tableName = "tasks_fts")
data class TaskFts(
    val title: String,
    val description: String,
)

@Dao
interface TaskDao {
    @Query("""
        SELECT tasks.* FROM tasks
        JOIN tasks_fts ON tasks.rowid = tasks_fts.rowid
        WHERE tasks_fts MATCH :query
    """)
    fun search(query: String): Flow<List<Task>>
}

FTS queries use the MATCH operator, not LIKE. Search terms support prefix matching with * (e.g. "prod*") and boolean operators (AND, OR, NOT).

Migrations

Auto-migration (Room 2.4+)

For simple schema changes (add column, add table), Room can generate migrations automatically.

@Database(
    entities = [Task::class],
    version = 2,
    autoMigrations = [AutoMigration(from = 1, to = 2)],
)
abstract class AppDatabase : RoomDatabase()

For renames or deletes, provide a spec:

@RenameColumn(tableName = "tasks", fromColumnName = "done", toColumnName = "isCompleted")
class Migration1To2 : AutoMigrationSpec

@Database(
    entities = [Task::class],
    version = 2,
    autoMigrations = [AutoMigration(from = 1, to = 2, spec = Migration1To2::class)],
)
abstract class AppDatabase : RoomDatabase()

Manual migration

val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(db: SupportSQLiteDatabase) {
        // Create new table with new schema
        db.execSQL("""
            CREATE TABLE tasks_new (
                id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
                title TEXT NOT NULL,
                isCompleted INTEGER NOT NULL DEFAULT 0,
                priority INTEGER NOT NULL DEFAULT 0
            )
        """)
        // Copy data
        db.execSQL("""
            INSERT INTO tasks_new (id, title, isCompleted)
            SELECT id, title, isCompleted FROM tasks
        """)
        // Swap
        db.execSQL("DROP TABLE tasks")
        db.execSQL("ALTER TABLE tasks_new RENAME TO tasks")
    }
}

Testing Room

@RunWith(AndroidJUnit4::class)
class TaskDaoTest {
    private lateinit var db: AppDatabase
    private lateinit var taskDao: TaskDao

    @Before
    fun setup() {
        db = Room.inMemoryDatabaseBuilder(
            ApplicationProvider.getApplicationContext(),
            AppDatabase::class.java,
        ).allowMainThreadQueries().build()
        taskDao = db.taskDao()
    }

    @After
    fun teardown() {
        db.close()
    }

    @Test
    fun insertAndRead() = runTest {
        val task = Task(title = "Test task")
        taskDao.insert(task)

        val tasks = taskDao.getAll().first()
        assertThat(tasks).hasSize(1)
        assertThat(tasks[0].title).isEqualTo("Test task")
    }
}

Use inMemoryDatabaseBuilder for tests - it's fast and doesn't persist. Use allowMainThreadQueries() only in tests, never in production.

Performance tips

• Use @ColumnInfo(index = true) on columns used in WHERE or JOIN clauses
• Avoid SELECT * in queries returning many rows - select only needed columns
• Use PagingSource from Paging 3 for large datasets instead of Flow<List<T>>
• Enable WAL mode (default since Room 2.0) for concurrent read/write performance
• Use @Upsert (Room 2.5+) instead of @Insert(onConflict = REPLACE) to avoid unnecessary deletes and re-inserts