kotlin-android

# Native Android with Kotlin & Compose You build production native Android: **Kotlin + Jetpack Compose + the UDF layered architecture** (UI → domain → data). One rule governs everything: **state flows down, events flow up, and there is exactly one source of truth per piece of state.** Get that rule right and recomposition, rotation, and testing fall into place; break it and you get a screen that compiles but recomposes every frame, leaks coroutine scopes, blocks the main thread, or drops state on rotation. This skill exists to stop the agent from reaching for the 2015 playbook — XML layouts, `findViewById`, `AsyncTask`, `LiveData` inside Compose, `GlobalScope.launch`, `MutableState` exposed straight out of a `ViewModel`. Emit a buildable, idiomatic module, not a toy. ## Versions floor (2026) These are **floors verified against current docs (2026-06)**. Re-check the matrix before locking — Compose and AGP move together and a mismatch fails the build. | Piece | Floor | Why it matters | |---|---|---| | Kotlin (KGP) | **2.2.x** | K2 compiler is default & Stable; KGP must align with AGP. | | AGP | **9.2+** when using Compose | Compose's compileSdk 37 requires AGP ≥ 9.2.0. | | compileSdk | **37** | Current Compose target. | | minSdk | **24** | Practical modern floor (~99% devices); Compose technically supports 21+. | | JDK (build) | **17** | Required by current AGP/Compose toolchain. | | Compose BOM | **2026.05.01** → Compose 1.11.2 | Pin artifacts via the BOM, never per-artifact versions. | | Navigation | **2.8+** | Type-safe `@Serializable` routes land here. | | Hilt + Room + Retrofit | current | DI / persistence / network. Wire Room & Hilt with **KSP, not kapt**. | | Serialization | kotlinx.serialization | Retrofit converter + Navigation route types. | ## The architecture in one screen Three layers. Higher layers depend on lower; never the reverse. ```text UI layer Composable (stateless) ── reads ──> UiState │ events up ▲ state down ViewModel exposes StateFlow<UiState> │ │ calls domain layer (optional) UseCase — only when logic spans repos or is reused │ calls data layer Repository (interface in domain, impl here) ├── Room DAO → Flow (single source of truth) └── Retrofit → suspend (refreshes the source of truth) ``` - **UI** is dumb: render `UiState`, send events. No business logic in a `@Composable`. - **domain** is optional: add use-cases only when a screen needs logic from >1 repository. - **data** owns truth: the repository decides; Room is the cache that the UI observes. Offline-first means **Room is the source of truth**. The network writes into Room; the UI observes Room's `Flow`. `WorkManager` does background sync. The UI never reads the network directly. ## State & recomposition Each rule has a one-line reason. - **Hoist state.** A composable that owns mutable state can't be reused or previewed — pass state in, send events out. - **`remember` survives recomposition; `rememberSaveable` survives rotation/process death.** Use `rememberSaveable` for anything the user would be annoyed to lose (scroll, input). - **`derivedStateOf` for computed state** — recomputes only when its inputs change, not every recomposition. - **`key()` / stable keys in `LazyColumn`** — without a stable item key, reorder/insert churns the whole list. - **Business logic never lives in a `@Composable`** — composables run on every recomposition. ```kotlin // Bad — logic + I/O in the composable; runs on every recomposition. @Composable fun ArticlesScreen(repo: ArticleRepository) { val articles = runBlocking { repo.fetch() } // blocks UI thread, refetches constantly LazyColumn { items(articles) { Text(it.title) } } } // Good — stateless UI driven by hoisted state; logic in the ViewModel. @Composable fun ArticlesScreen(state: ArticlesUiState, onRetry: () -> Unit) { when (state) { ArticlesUiState.Loading -> CircularProgressIndicator() is ArticlesUiState.Error -> ErrorView(state.message, onRetry) is ArticlesUiState.Success -> LazyColumn { items(state.articles, key = { it.id }) { Text(it.title) } } } } ``` ## ViewModel + UI state Model the screen as a **sealed `UiState`** so impossible states (loading *and* error) can't exist. Expose it as `StateFlow`, never a mutable type. ```kotlin sealed interface ArticlesUiState { data object Loading : ArticlesUiState data class Success(val articles: List<Article>) : ArticlesUiState data class Error(val message: String) : ArticlesUiState } @HiltViewModel class ArticlesViewModel @Inject constructor( repository: ArticleRepository, ) : ViewModel() { val uiState: StateFlow<ArticlesUiState> = repository.observeArticles() .map<List<Article>, ArticlesUiState> { ArticlesUiState.Success(it) } .catch { emit(ArticlesUiState.Error(it.message ?: "Unknown error")) } .stateIn( scope = viewModelScope, started = SharingStarted.WhileSubscribed(5_000), initialValue = ArticlesUiState.Loading, ) } ``` Collect it lifecycle-aware so collection pauses below `STARTED` and you don't burn work off-screen: ```kotlin @Composable fun ArticlesRoute(viewModel: ArticlesViewModel = hiltViewModel()) { val state by viewModel.uiState.collectAsStateWithLifecycle() ArticlesScreen(state = state, onRetry = viewModel::refresh) } ``` `WhileSubscribed(5_000)` keeps the flow alive 5s past the last collector so a rotation doesn't restart the upstream pipeline. ## Data layer The repository interface lives in domain; its implementation lives in data. Retrofit uses `suspend` functions and a `@Serializable` DTO; Room DAOs return `Flow`. Errors surface as a sealed result, not raw exceptions thrown into the UI. ```kotlin interface ArticleRepository { fun observeArticles(): Flow<List<Article>> // from Room — the source of truth suspend fun refresh() // network -> Room } ``` The full wired example — DTO, entity, DAO, Retrofit service, repository impl, mappers, offline-first refresh — is in **[references/architecture.md](references/architecture.md)**. Read it before scaffolding a feature end-to-end. ## DI with Hilt `@HiltAndroidApp` on the `Application`, `@Module @InstallIn(SingletonComponent::class)` for bindings, `@HiltViewModel` + `hiltViewModel()` for screens. Prefer **constructor injection**; reach for `@Provides`/`@Binds` only for interfaces and third-party types you don't own. Classic error: `MyRepo cannot be provided without an @Inject constructor`. Fix one of: either add `@Inject constructor(...)` to the concrete class, or `@Binds` the interface to its implementation inside an installed module. See **[references/gradle-setup.md](references/gradle-setup.md)** for the KSP wiring that makes Hilt generate. ## Coroutines & Flow rules - **Never `GlobalScope.launch`** — it outlives every screen and leaks. Use `viewModelScope` (UI logic) or a repository-scoped scope. - **Structured concurrency**: a cancelled parent cancels children — keep work inside a real scope so navigation-away cancels it. - **Inject dispatchers** (`@IoDispatcher CoroutineDispatcher`) instead of hardcoding `Dispatchers.IO` — otherwise the work isn't testable. - **`flowOn` to switch a flow's upstream context**, not `withContext` inside a `flow { }` builder (which is a context-preservation violation). - **Cold `Flow` for streams, `StateFlow` for current-value state** — don't `collect` a cold flow when the UI needs the latest value. ## Navigation (type-safe) Since Navigation 2.8, routes are `@Serializable` types — the compiler checks your args. ```kotlin @Serializable data object ArticleList @Serializable data class ArticleDetail(val id: String) NavHost(navController, startDestination = ArticleList) { composable<ArticleList> { ArticlesRoute(onOpen = { navController.navigate(ArticleDetail(it)) }) } composable<ArticleDetail> { backStackEntry -> val args = backStackEntry.toRoute<ArticleDetail>() ArticleDetailRoute(id = args.id) } } ``` No string routes, no manual `arguments = listOf(navArgument(...))`, no fragile key parsing. ## Build & verify ```bash ./gradlew :app:assembleDebug lintDebug testDebugUnitTest ``` `assembleDebug` proves it builds, `lintDebug` catches Android lint, `testDebugUnitTest` runs JVM unit tests. For a fast, **SDK-free** static gate over the Kotlin/Gradle you just wrote, run `scripts/verify.sh` — it greps for banned patterns and missing modern ones without touching the Android SDK, so it works in CI or a bare checkout. ## Anti-patterns | Anti-pattern | Why it bites | Do instead | |---|---|---| | XML layouts + `findViewById` | Stale; no compile-time view safety; doesn't compose | Jetpack Compose `@Composable` | | `LiveData` collected in a Composable | Lifecycle mismatch, extra dependency, not Compose-native | `StateFlow` + `collectAsStateWithLifecycle()` | | `GlobalScope.launch` | Leaks; outlives the screen; uncancellable | `viewModelScope` / scoped coroutine | | `runBlocking` / network call on the main thread | ANR, frozen UI | `suspend` on an injected dispatcher | | Business logic in a `@Composable` | Runs every recomposition; untestable | Move to ViewModel / use-case | | `MutableStateFlow`/`mutableStateOf` exposed publicly | UI can mutate state; breaks single source of truth | private mutable backing + public `asStateFlow()`/`StateFlow` | | God-Activity holding all state | Untestable, rotation-fragile | One ViewModel per screen, hoisted state | | `kapt` for Room/Hilt | Slow, legacy; K2-incompatible edge cases | **KSP** | | `collectAsState()` in Compose | Keeps collecting off-screen, wastes work | `collectAsStateWithLifecycle()` | | Reading the network directly in the repository's read path | No offline; UI flickers on every fetch | Room as source of truth; network refreshes it | ## When this is the wrong skill - **Shared UI across Android + iOS + desktop from one Kotlin codebase** — the moment `commonMain`, `expect/actual`, or an iOS target appears, use [../compose-multiplatform/SKILL.md](../compose-multiplatform/SKILL.md). - **Server-side Kotlin / JVM web backend** the app talks to → [../spring-boot/SKILL.md](../spring-boot/SKILL.md). - **Pure Kotlin/JVM language questions, no Android** → [../java/SKILL.md](../java/SKILL.md) is the nearest JVM-language sibling (there is no standalone `kotlin` language skill). - **iOS/SwiftUI** → `swift-ios`. **Dart cross-platform** → [../flutter/SKILL.md](../flutter/SKILL.md). **React Native** → `react-native`. - **CI for `assembleDebug`/tests** → `github-actions`. ## References - [references/architecture.md](references/architecture.md) — end-to-end wired feature (UiState + ViewModel + Repository + Room + Retrofit + Hilt), complete file contents. - [references/gradle-setup.md](references/gradle-setup.md) — `libs.versions.toml`, root + module `build.gradle.kts`, the Compose Kotlin plugin, Hilt/KSP wiring, and common Gradle/build error fixes.