3.3.0-alpha02

📊 Performance Metrics

New artifact: :metrics is here!

With FlowMVI in just a 5 lines of code you can now set up metrics collection to understand the performance and usage patterns of your app!

FlowMVI metrics collect over 66 different stats including speed of intent handling, state updates, error frequencies, data loading delays, bootstrapping time and lifecycle events, and more, then lets you upload to any popular metrics ingestion service such as OpenTelemetry, Prometheus, OpenMetrics etc, and visualize them in dashboards:

val metrics = collectMetrics(
    reportingScope = applicationScope
)
reportMetrics(
    metrics = metrics,
    sink = OtlpJsonSink(BackendSink()), 
)

The debugger IDE plugin and desktop apps have been upgraded to support the ingestion of metrics and also visualize them in a similar way out of the box, with minimal setup required to send metrics to the debugger:

Screen.Recording.2025-12-14.at.11.06.00.AM.mov

Metrics are being benchmarked and are optimized to minimally influence the performance of your business logic, so that you can just plug them in your store configuration once and enjoy the benefits everywhere.

Get started by reading the documentation

🚀 New Hooks:

• onActionDispatch hook will trigger when side-effects are dequeued, as opposed to onAction which triggers when enqueued
• onIntentEnqueue hook will trigger when intents are enqueued, as opposed to onIntent which triggers when dequeued

ShutdownContext

ShutdownContext now implements StoreLifecycle which holds a reference to the last store lifetime. Previously, any lifecycle was
grabbed from the Store itself which may not be the one that onStop was invoked with. This should improve reliability.

This may be a behavioral breaking change if you relied on StoreLifecycle inside of onStop. Worth double-checking your onStop hooks to be safe.

🚢 Other New Stuff

Note: Debugger of version 3.3.0 may be incompatible with FlowMVI 3.2x and older, downgrade or upgrade one of these to fix.

• Debugger will now merge events from stores if they have the same name
• Add debounceIntents decorator
• Migrate PluginTestScope to be an interface instead of class.
• Add validation to BatchIntentsDecorator modes. Worth re-checking that you don't pass invalid values there before shipping.
• Each StoreConfiguration now has storeId a unique UUID of the store instance. Using static unique names is now even more important with metrics to aggregate events per-screen reliably.

🐞 Bug Fixes

Important fix: onUndeliveredAction callback wasn't properly wired and was never invoked since 3.1.0, fixed with this release + tests added that should prevent such issues in the future.

• add failsafe to debug client store when events can't be deserialized
• add failsafe to debug server when events can't be deserialized
• let StoreConfiguration's state be covariant

Deps

• Kotlin 2.3.0-RC3
• Compose 1.10-rc1
• Ktor 3.3.3

Safe upgrade checklist

• Check onStop callbacks that use StoreLifecycle methods awaitUntilClosed etc for correctness
• Upgrade debugger IDE plugin
• Check onUndeliveredAction usages which should now work
• Check batchIntents decorator configuration for validity of passed values
• Wire/migrate to onActionDispatch or onIntentEnqueue based on your needs (analytics plugins etc)

---

Rest of the changelog

• add metrics decorator
• feat!: let ShutdownContext implement StoreLifecycle and pass one-time shutdown context there
• refactor metrics collector for safe event handling across restarts
• implement Metrics api for decoupling metric collection and flushing
• implement default metrics flusher plugin
• implement OpenMetricsSink
• implement otel metrics
• add metrics schema versioning surface
• add metrics showcase to the sample app
• implement benchmarks evaluating metrics collection overhead
• add debounce intents decorator
• feat!: let ShutdownContext implement StoreLifecycle and pass one-time shutdown context there
• add debounce intents decorator
• feat!: add validation to BatchIntentsDecorator modes
• add wasm-wasi target to metrics and common debugger code
• introduce stable store IDs for debugging and metrics
• enable wasmJs and js for debugger plugin module
• implement DebuggerSink for metrics, wire metrics to sample app
• add storeName parameter to client events
• accumulate metrics in debug server
• implement metrics visualization in the debugger
• add documentation for metrics visualization in debugger
• update deps
• downgrade kotest due to kotest/kotest#5203
• apply hack for JetBrains/intellij-platform-gradle-plugin#2062
• downgrade intellij plugin due to JetBrains/intellij-platform-gradle-plugin#2062
• migrate compose deps to version catalog
• replace material debugger icons with custom iconpack
• migrate sample app from material icons extended dependency
• temporarily set logging level to quiet to silence fp warning
• cover enqueue dispatch hooks with tests
• update agents and SECURITY.md
• provide fixed timestamp for tests to otel metrics mapper
• remove fluxo benchmarks
• add tests for sinks and basic apis
• more tests for edge cases of sinks
• add tests for quantiles/ema/perfmetrics
• cleanup to improve testability of new metrics internals
• add tests for debounce decorator
• add test utils for metrics
• enhance and simplify test dsl for new tests
• add utils to test metrics with real store
• add full test suite for the MetricsCollector and plugin composition
• align collector tests
• update readme with metrics and more benefits, reduce size
• temp remove claude workflow
• update agents and SECURITY.md
• added testing guidance for agents
• create a documentation page on Metrics

Full Changelog: 3.2.1...3.3.0-alpha02