Article about this library: Every Composable deserves a ViewModel

Resaca 🍹

The right scope for objects and View Models in Android Compose.

Resaca provides a simple way to keep a Jetpack ViewModel (or any other object) in memory during the lifecycle of a @Composable function and automatically clean it up when not needed anymore. This means, it retains your object or ViewModel across recompositions, during configuration changes, and also when the container Fragment or Compose Navigation destination goes into the backstack.

With Resaca you can create fine grained ViewModels for fine grained Composables and finally have reusable components across screens.

Why

Compose allows the creation of fine-grained UI components that can be easily reused like Lego blocks 🧱. Well architected Android apps isolate functionality in small business logic components (like use cases, interactors, repositories, etc.) that are also reusable like Lego blocks 🧱.

Screens are built using Compose components together with business logic components, and the standard tool to connect these two types of components is a Jetpack ViewModel. Unfortunately, ViewModels can only be scoped to a whole screen (or larger scope), but not to smaller Compose components on the screen.

In practice, this means that we are gluing UI Lego blocks with business logic Lego blocks using a big glue class for the whole screen, the ViewModel 🗜.

Until now...

Installation

Add the Jitpack repo and include the library (less than 5Kb):

// In settings.gradle.kts
dependencyResolutionManagement {
    repositories {
         [..]
         maven { setUrl("https://jitpack.io") }
    }
}
// In module's build.gradle.kts
dependencies {
    // The latest version of the lib is available in the badget at the top, replace X.X.X with that version
    implementation("com.github.sebaslogen.resaca:resaca:X.X.X")
}

allprojects {
    repositories {
        [..]
        maven { url "https://jitpack.io" }
    }
}
dependencies {
    // The latest version of the lib is available in the badget at the top, replace X.X.X with that version
    implementation 'com.github.sebaslogen.resaca:resaca:X.X.X'
}

Usage

Inside your @Composable function create and retrieve an object using rememberScoped to remember any type of object (except ViewModels). For ViewModels use viewModelScoped. That's all 🪄✨

Examples:

@Composable
fun DemoScopedObject() {
    val myRepository: MyRepository = rememberScoped { MyRepository() }
    DemoComposable(inputObject = myRepository)
}

@Composable
fun DemoScopedViewModel() {
    val myScopedVM: MyViewModel = viewModelScoped()
    DemoComposable(inputObject = myScopedVM)
}

@Composable
fun DemoScopedViewModelWithDependency() {
    val myScopedVM: MyViewModelWithDependencies = viewModelScoped { MyViewModelWithDependencies(myDependency) }
    DemoComposable(inputObject = myScopedVM)
}

@Composable
fun DemoViewModelWithKey() {
    val scopedVMWithFirstKey: MyViewModel = viewModelScoped("myFirstKey") { MyViewModel("myFirstKey") }
    val scopedVMWithSecondKey: MyViewModel = viewModelScoped("mySecondKey") { MyViewModel("mySecondKey") }
    // We now have 2 ViewModels of the same type with different data inside the same Composable scope
    DemoComposable(inputObject = scopedVMWithFirstKey)
    DemoComposable(inputObject = scopedVMWithSecondKey)
}

@Composable
fun DemoKoinInjectedViewModelWithDependency() {
    val myInjectedScopedVM: MyViewModelWithDependencies = viewModelScoped() { getKoin().get { parametersOf(myConstructorDependency) } }
    DemoComposable(inputObject = myInjectedScopedVM)
}

Once you use the rememberScoped or viewModelScoped functions, the same object will be restored as long as the Composable is part of the composition, even if it temporarily leaves composition on configuration change (e.g. screen rotation, change to dark mode, etc.) or while being in the backstack.

For ViewModels, in addition to being forgotten when they're really not needed anymore, their coroutineScope will also be automatically canceled because ViewModel's onCleared method will be automatically called by this library.

💡 Optional key: a key can be provided to the call, rememberScoped(key) { ... } or viewModelScoped(key) { ... }. This makes possible to forget an old object when there is new input data during a recomposition (e.g. a new input id for your ViewModel).

⚠️ Note that ViewModels remembered with viewModelScoped should not be created using any of the Compose viewModel() or ViewModelProviders factories, otherwise they will be retained in the scope of the screen regardless of viewModelScoped. Also, if a ViewModel is remembered with rememberScoped its clean-up method won't be called, that's the reason to use viewModelScoped instead.

Sample use cases

Here are some sample use cases reported by the users of this library:

• 📃📄 Multiple instances of the same type of ViewModel in a screen with a view-pager. This screen will have multiple sub-pages that use the same ViewModel class with different ids. For example, a screen of holiday destinations with multiple pages and each page with its own HolidayDestinationViewModel.
• ❤️ Isolated and stateful UI components like a favorite button that are widely used across the screens. This FavoriteViewModel can be very small, focused and only require an id to work without affecting the rest of the screen's UI and state.
• 🗪 Dialog pop-ups can have their own business-logic with state that is better to isolate in a separate ViewModel but the lifespan of these dialogs might be short, so it's important to clean-up the ViewModel associated to a Dialog after it has been closed.

Demo app

Demo app documentation can be found here.

Before	After backstack navigation & configuration change

Dependency injection support

This library does not influence how your app provides or creates objects so it's dependency injection strategy and framework agnostic.

Nevertheless, this library supports two of the main dependency injection frameworks:

Hilt 🗡️

HILT (Dagger) support is available in a small extension of this library: resaca-hilt.

Documentation and installation instructions are available here.

Koin 🪙

Koin is out of the box supported by simply changing the way you request a dependency.

Instead of using the getViewModel or koinViewModel functions from Koin, you have to use the standard way of getting a dependency from Koin getKoin().get().

Usage example: val viewModel: MyViewModel = viewModelScoped(myId) { getKoin().get { parametersOf(myId) } }

Note: if you plan to use a ViewModel with a SavedStateHandle, then you need to use the koinViewModelScoped function from the small extension library resaca-koin.

General considerations for State Hoisting

Here are a few suggestions of how to provide objects in combination with this library in a Compose screen:

• When using the Lazy* family of Composables it is recommended that you use rememberScoped/viewModelScoped outside the scope of Composables created by Lazy constructors (e.g. LazyColumn) because there is a chance that a lazy initialized Composable will be disposed of when it is not visible anymore (e.g. scrolled away) and that will also dispose of the rememberScoped/viewModelScoped object (after a few seconds), this might not be the intended behavior. For more info see Compose's State Hoisting.
• When a Composable is used more than once in the same screen with the same input, then the ViewModel (or business logic object) should be provided only once with viewModelScoped at a higher level in the tree using Compose's State Hoisting.

Why not use remember?

Remember will keep our object alive as long as the Composable is not disposed of. Unfortunately, there are a few cases where our Composable will be disposed of and then added again, breaking the lifecycle parity with the remember function. 😢

RememberSaveable will follow the lifecycle of the Composable, even in the few cases where the Composable is temporarily disposed of. But the object we want to remember needs to implement Parcelable or the Saver interface in an additional class. 😢 Implementing these interfaces might not trivial.

The new RememberScoped 🪄✨

RememberScoped function keeps objects in memory during the lifecycle of the Composable, even in a few cases where the Composable is disposed of, and then added again. Therefore, it will retain objects longer than the remember function but shorter than rememberSaveable because there is no serialization involved.

Lifecycle

RememberScoped function keeps objects in memory during the lifecycle of the Composable, even in a few cases where the Composable is disposed of, and then added again.

RememberScoped lifecycle internal implementation details

This project uses internally a ViewModel as a container to store all scoped ViewModels and scoped objects.

Lifecycle example

This diagram shows the lifecycle of three Composables (A, B, and C) with their respective objects scoped with the rememberScoped function. All these Composables are part of a Composable destination which is part of a Fragment which is part of an Activity which is part of the App. The horizontal arrows represent different lifecycle events, events like Composable being disposed of, Composable screen going into the backstack, Fragment going into the backstack and returning from backstack, or Activity recreated after a configuration change.

The existing alternatives to replicate the lifecycle of the objects in the diagram without using rememberScoped are:

• Object A lifecycle could only be achieved using the Compose viewModel() or ViewModelProviders factories.
• Object B lifecycle could only be achieved using the Compose remember() function.
• Object C lifecycle could not be achieved neither by using ViewModel provider functions nor Compose remember functions.