Lightweight, leak‑free bridge delivering one‑way UI commands from shared ViewModels to native implementations; automatic weak references, sticky queued actions, main‑thread execution, easy testing.
Surfaced from shared tags and platforms — no rankings paid for.
Dispatch UI commands (Toast, Navigation, Permissions) from shared ViewModels to Android and iOS — leak-free, rotation-safe, always on the Main Thread.
Most mobile apps treat everything (Toasts, Navigation, Alerts) as State. This is why you see "Ghost Toasts" popping up after rotation, or users stuck because a navigation event fired in the 300ms "blind spot" during an Activity restart.
KRelay is a Buffered Multicasting bridge. Your shared ViewModel signals an intent, and the platform fulfills it — exactly once, always on the Main Thread, even if the UI wasn't ready when you called it.
"State is for seeing, Event is for running."
KRelay is designed for mission-critical systems (VoIP, Fintech, SOS) where event delivery is non-negotiable.
Read the State vs. Event: Why your MVI/Redux app is probably leaking side-effects.
// shared/build.gradle.kts
commonMain.dependencies {
implementation("dev.brewkits:krelay:2.1.1")
implementation("dev.brewkits:krelay-compose:2.1.1") // Compose helpers (optional)
}
1. Define a contract in commonMain
interface ToastFeature : RelayFeature {
fun show(message: String)
}
2. Dispatch from your ViewModel
class LoginViewModel : ViewModel() {
fun onLoginSuccess() {
KRelay.dispatch<ToastFeature> { it.show("Welcome back!") }
// Zero platform imports. Zero leaks. Queued if the UI isn't ready yet.
}
}
3. Register the platform implementation
// Android — Activity or Composable
KRelay.register<ToastFeature>(object : ToastFeature {
override fun show(message: String) =
Toast.makeText(this@MainActivity, message, Toast.LENGTH_SHORT).show()
})
// iOS — Swift
let toastClass = KRelayKClassHelpersKt.toastFeatureKClass()
KRelayIosHelperKt.registerFeature(
instance: KRelay.shared.instance,
kClass: toastClass,
impl: IOSToast(viewController: self)
)
That's all the wiring needed. KRelay routes the call to the Main Thread, replays it if the UI wasn't ready, and releases the implementation when it's GC'd.
ViewModel KRelay Platform
─────────────────────────────────────────────────────────────
dispatch<Toast> { ... } ──► impl registered?
├── yes: runOnMain { block(impl) }
└── no: sticky queue ──► replay on register()
Three guarantees, always active:
onDestroy cleanup needed for 99% of cases.dispatch is called from, the block executes on Android's Looper.mainLooper() / iOS's GCD main queue.The API is identical on the global singleton and on any isolated instance.
// Registration
KRelay.register<ToastFeature>(impl)
KRelay.unregister<ToastFeature>() // unconditional
KRelay.unregister<ToastFeature>(impl) // identity-safe (won't clear a newer registration)
KRelay.isRegistered<ToastFeature>()
// Dispatch
KRelay.dispatch<ToastFeature> { it.show("Hello") }
KRelay.dispatchWithPriority<ToastFeature>(ActionPriority.CRITICAL) { it.show("Error!") }
// Queue management
KRelay.getPendingCount<ToastFeature>()
KRelay.clearQueue<ToastFeature>()
// Scope tokens — cancel queued actions by caller identity
token = scopedToken()
KRelay.dispatch<ToastFeature>(token) { it.show() }
KRelay.cancelScope(token)
KRelay.dump()
KRelay.debugMode =
When multiple actions queue up before an implementation registers, higher-priority actions replay first. On overflow, the lowest-priority action is evicted (not just the oldest).
KRelay.dispatchWithPriority<NavFeature>(ActionPriority.HIGH) { it.goToHome() }
KRelay.dispatchWithPriority<NavFeature>(ActionPriority.CRITICAL) { it.showError("Timeout") }
// ActionPriority: LOW(0) NORMAL(50) HIGH(100) CRITICAL(1000)
Survives process death. The action is saved to SharedPreferences (Android) or NSUserDefaults (iOS) and restored on next launch.
// Register a factory to reconstruct the action from its payload
instance.registerActionFactory<ToastFeature>("toast", "show") { payload ->
{ feature -> feature.show(payload) }
}
// Dispatch — persisted to disk if no impl is available
instance.dispatchPersisted<ToastFeature>("toast", "show", "Payment received")
// On app restart — restores actions into the in-memory queue
instance.restorePersistedActions()
Use an explicit string
featureKey(not the class name) — class names can be obfuscated by ProGuard/R8.
The singleton is fine for small apps. For multi-module projects or Koin/Hilt injection, create isolated instances:
// Each module owns its registry — no cross-module interference
val rideKRelay = KRelay.create("Rides")
val foodKRelay = KRelay.create("Food")
// Or with custom settings via builder
val krelay = KRelay.builder("Payment")
.maxQueueSize(50)
.actionExpiry(60_000L)
.debugMode(BuildConfig.DEBUG)
.build()
Inject into ViewModels via Koin:
val appModule = module {
single { KRelay.create("AppScope") }
viewModel { LoginViewModel(krelay = get()) }
}
class LoginViewModel(private val krelay: KRelayInstance) : ViewModel() {
fun onSuccess() { krelay.dispatch<NavFeature> { it.goToHome() } }
}
Add krelay-compose and use the built-in helpers:
// Registers when composition enters, unregisters when it leaves
@Composable
fun HomeScreen() {
val context = LocalContext.current
KRelayEffect<ToastFeature> {
object : ToastFeature {
override fun show(message: String) =
Toast.makeText(context, message, Toast.LENGTH_SHORT).show()
}
}
// ...
}
// When you need to use the implementation in the same composable
@Composable
fun HomeScreen() {
val snackbarState = remember { SnackbarHostState() }
val scope = rememberCoroutineScope()
rememberKRelayImpl<ToastFeature> {
object : ToastFeature {
override fun show(message: String) {
scope.launch { snackbarState.showSnackbar(message) }
}
}
}
Scaffold(snackbarHost = { SnackbarHost(snackbarState) }) { ... }
}
Both helpers accept an optional instance parameter for the Instance API:
KRelayEffect<ToastFeature>(instance = myKRelayInstance) { ... }
Manual
DisposableEffect? Always hoist the implementation intoremember {}. Without it, Kotlin/Native's GC can collect the object before the first dispatch.See Compose Integration Guide for full patterns including Navigation Compose and Voyager.
No mocking library required. Inject a real KRelayInstance and register plain Kotlin objects.
Run the test suite:
./gradlew :krelay:test # JVM (fast)
./gradlew :krelay:iosSimulatorArm64Test # iOS Simulator
./gradlew :krelay:connectedDebugAndroidTest # Real Android device
By default, three passive protections apply to every queued action:
For granular control, use scope tokens to cancel only the actions queued by a specific ViewModel:
class MyViewModel : ViewModel() {
private val token = scopedToken()
fun doWork() = KRelay.dispatch<WorkFeature>(token) { it.run() }
override fun onCleared() = KRelay.cancelScope(token)
}
KRelay is for one-way, fire-and-forget UI commands. For anything else, use the right tool:
KRelay is framework-agnostic. It connects to whatever navigation, media, or permission library you already use — ViewModels stay clean of all framework imports.
See Integration Guides for step-by-step examples.
Platforms: Android arm64 · Android x86_64 · iOS arm64 (device) · iOS arm64 (simulator) · iOS x64 (simulator)
KRelay.create("ScopeName") — isolated instances per moduleKRelay.builder(...) — configure queue, expiry, and debug mode per instanceKRelayInstance is an interface, injectable via Koin or HiltCopyright 2026 Brewkits
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Made with care by Nguyễn Tuấn Việt · Brewkits
| Approach | The Pain Point |
|---|
Pass Activity / UIViewController | Memory leaks and onDestroy boilerplate |
SharedFlow(replay=0) | Events are lost during screen rotation |
StateFlow as Event | Double-execution / Side-effects that "stick" |
Channels | Single-observer only (unsuitable for UI + Analytics) |
private lateinit var krelay: KRelayInstance
private lateinit var viewModel: LoginViewModel
fun setup() {
krelay = KRelay.create("TestScope")
viewModel = LoginViewModel(krelay = krelay)
}
fun tearDown() {
krelay.reset()
}
fun `login success shows toast and navigates`() {
val toast = MockToast()
val nav = MockNav()
krelay.register<ToastFeature>(toast)
krelay.register<NavFeature>(nav)
viewModel.onLoginSuccess()
assertEquals("Welcome back!", toast.lastMessage)
assertEquals("home", nav.lastDestination)
}
class MockToast : ToastFeature {
var lastMessage: String? = null
override fun show(message: String) { lastMessage = message }
}
class MockNav : NavFeature {
var lastDestination: String? = null
override fun navigateTo(screen: String) { lastDestination = screen }
}
| Protection | Default | Behaviour |
|---|
WeakReference | Always on | Platform impls released when GC'd — no onDestroy cleanup needed |
actionExpiryMs | 5 min | Queued actions expire and are dropped automatically |
maxQueueSize | 100 | When full, lowest-priority (or oldest) action is evicted |
| Scenario | Better alternative |
|---|
| Need a return value | suspend fun + expect/actual |
| Reactive UI state | StateFlow / MutableStateFlow |
| Critical side-effects (payment, upload) | WorkManager / background service |
| Database | Room / SQLDelight |
| Network | Ktor + Repository |
| Category | Library |
|---|
| Navigation | Voyager · Decompose · Navigation Compose |
| Media | Peekaboo (image/camera picker) |
| Permissions | Moko Permissions |
| Biometrics | Moko Biometry |
| Reviews | Play Core · StoreKit |
| DI | Koin · Hilt |
| KRelay | Kotlin | AGP | Android minSdk | iOS |
|---|
| 2.1.x | 2.1.x | 8.x | 24 | 14.0+ |
| 2.0.x | 2.1.x | 8.x | 24 | 14.0+ |
| 1.1.x | 2.0.x | 8.x | 23 | 13.0+ |
| 1.0.x | 1.9.x | 7.x | 21 | 13.0+ |
krelay-compose artifact — KRelayEffect<T> and rememberKRelayImpl<T> published as dev.brewkits:krelay-compose:2.1.1, separate from the zero-dependency core.registerActionFactory and dispatchPersisted now require an explicit stable featureKey string. Old overloads deprecated with replaceWith guidance.unregister — unregister(impl) only removes the registration if the stored reference matches, preventing a recomposing Compose component from clearing a newer registration.KRelayMetrics operations are now lock-protected.registerFeature validates interface conformance at runtime; crashes in debug, warns in release.KRelayEffect<T> and rememberKRelayImpl<T> Compose helpersdispatchPersisted<T>() — survives process deathSharedPreferencesPersistenceAdapter (Android) and NSUserDefaultsPersistenceAdapter (iOS)scopedToken() + cancelScope(token) for fine-grained ViewModel cleanupdispatchWithPriority available on instances (was singleton-only)resetConfiguration() without clearing the registry or queue| Guide | Description |
|---|
| Compose Integration | KRelayEffect, rememberKRelayImpl, Navigation Compose, Voyager |
| SwiftUI Integration | iOS-specific patterns, XCTest |
| Integration Guides | Voyager, Decompose, Moko, Peekaboo, DI |
| Lifecycle Guide | Activity · Fragment · UIViewController · SwiftUI |
| Testing Guide | Patterns, mocks, instrumented tests |
| Anti-Patterns | What not to do and why |
| Architecture | Internals deep dive |
| API Reference | Full API cheat sheet |
| Managing Warnings | Suppress @OptIn at module level |
| Migration to v2.0 | Upgrading from v1.x |