Add a developers menu to your Compose app with Tweaks

Motivations and how to use Tweaks library.
by Guillermo Merino Jimenez & Yamal Al-Mahamid

In our applications we have a developer menu that let us have debug information and flags to modify the configuration of the application

An example of an existing debug screen in an application based on Views

Several months ago, our team decided to implement all our new applications with a 100% Jetpack Compose based architecture. This means that we wanted to have:

• Only one Activity and screens hosted inside the navigation graph provided by Jetpack Compose Navigation
• Business logic allocated in states that can be observed (using Flow)
• And of course, all screens made by composable elements.

So, we wanted to create a library that offers the same functionality we had in the past, but built 100% using Compose.

What is a Tweak?

A debug variable that stores a primitive value visible in a screen in developer version of applications. They can be used to see information (like the user-id or the IP, for example), to let the user modify the behaviour of the app (overriding the API endpoint to use a different environment) or even add buttons that let the users navigate to sections of the app (that are not visible to them, for example)

What does Tweaks do?

It exposes a debug screen that can be configured via a DSL and store different categories of Tweaks. Tweaks can be read-only or writable and they can store and display primitive values.

Read-only Tweaks

Used to display information of the state of the application, for example the user-id of the current logged user.

Writable Tweaks

They let developers to modify parameters of the application in runtime, for example, the API endpoint.

Library Architecture

Basically the library exposes a DSL to model the screens and forms for each category. The DSL creates a graph of Tweak entries that is the state of the library.

Then, the TweakEntries are persisted in the DataStore, in case they need to. And finally, the graph is mapped to a NavigationGraph that can be added to the NavHost of Jetpack Compose Navigation.

Lastly, a Tweak state can be retrieved at any time and be observed, so the client’s code can use it.

Diagram of the Architecture

How to use it

First of all, add it to your build.gradle:

Then initialize the library in the Applications onCreate

The tweaksGraph is made of:

Categories

A category is a bunch of groups of tweaks, usually a feature or a component of an application.

Groups

Inside a category, there can be several groups of tweaks. For example a feature could have a debug and a setup group

Tweak Entries

A tweak entry is the atomic element of the graph, it is a write/read-only primitive value.

Also, a TweakGraph can contain a cover, a main group of tweaks that display top-level information of the application.

Example: Imagine that you want to add a screen to configure the Api Client of your application.

The screen resultant of the code from above

Once the Graph is created, it needs to be added to the NavHost of the application, that can be done with the NavGraphBuilder.addTweakGraph:

And finally, a Tweak can be read in any part of the application with getTweakValue, that returns the Tweak state.

For more configuration options, like shake gesture support, custom-screens or deeplinking, please check the library’s Readme