amethyst: Skill for Claude Code

Compose: side effects

Core principle

Composable bodies describe UI. They can be recomposed, skipped, or abandoned. Work that changes the outside world belongs in an effect API whose lifecycle matches the work.

Pick the smallest effect

Need	API
Publish Compose state to non-Compose code after every successful recomposition	SideEffect
Register/unregister a listener, callback, observer, or resource	DisposableEffect(keys...)
Run suspending, deferred, or keyed one-shot work	LaunchedEffect(keys...)
Launch suspending work from a user event callback	rememberCoroutineScope()
Convert Compose snapshot reads into a Flow inside a coroutine	snapshotFlow { ... } inside LaunchedEffect

Effect keys

Keys define restart identity. When any key changes, the old effect is cancelled/disposed and a new one starts.

// ✅ Restart collection when userId changes
LaunchedEffect(userId) {
    repository.events(userId).collect { event -> handle(event) }
}

// ❌ Unit hides a changing input; collection keeps using the first userId
LaunchedEffect(Unit) {
    repository.events(userId).collect { event -> handle(event) }
}

Use stable, semantic keys:

• Use the thing whose lifecycle the effect follows: userId, screenId, lifecycleOwner, focusRequester.
• Do not use broad objects (state, viewModel) when only one property matters.
• Do not add changing lambdas as keys unless you really want restarts on every lambda change.

Avoid stale captures

For long-running effects that should not restart but need the latest callback or value, use rememberUpdatedState.

@Composable
fun Timeout(onTimeout: () -> Unit) {
    val latestOnTimeout by rememberUpdatedState(onTimeout)

    LaunchedEffect(Unit) {
        delay(1_000)
        latestOnTimeout()
    }
}

Use this when the lifecycle is "start once" but the invoked lambda should stay fresh. Common cases:

• A timeout or splash effect should not restart when onTimeout changes, but it should call the latest callback.
• A lifecycle observer should stay registered to the same owner, but invoke the latest onStart / onStop lambdas.
• A long-running collector should keep its collection lifecycle, but call the latest event handler.