Implementing Version Catalogs in Android

Every day, we seek to improve and learn new concepts to facilitate mobile development using trends that allow us to achieve the same results more easily. For example, sometimes updating libraries in a mobile application through Gradle can become complicated. In this article, we'll see how to implement version catalogs in Android in a simple way.

Version catalogs allow us to add and maintain dependencies and plugins in a scalable manner. By using them in Gradle, we can manage these dependencies when we have multiple modules.

To start, we need to create a version catalog. This is done by adding a file named "libs.version.toml" to the root project's gradle folder.

TOML (Tom's Obvious, Minimal Language) is a configuration file format that is easy to read and write and is used in software applications and projects. It was designed to be a more readable and understandable replacement for other configuration formats like JSON, YAML, or XML.

Among its features, we can mention its readability, hierarchical structure, and simple data types, as well as its extensibility, which allows adding new functionalities or data types as needed.

Once our file is created, we need to add the following sections:

[versions]
[libraries]
[plugins]

These sections are used as follows:

The versions section defines all variables containing the versions of dependencies and plugins, which will be used in the following blocks (libraries and plugins).
In the libraries section, we define the dependencies, and finally, in plugins, the plugins.
To perform a correct migration to version catalogs, we first add each dependency within the versions and libraries sections. Then, we synchronize our project and replace the statements in the build files with their equivalents within the catalog.

For example, the following code snippet shows how a library would change from being like this:

dependencies {
    implementation("androidx.core:core-ktx:1.9.0")
}

to looking like this:

dependencies {
   implementation(libs.androidx.ktx)
}

If we check the code inside the catalog, we can notice:

[versions]
ktx = "1.9.0"

[libraries]
androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }

The versions section contains the version of the library, and the libraries section uses this library to define the dependency using a more natural and understandable language.

Similarly, we can migrate plugins to catalogs. Simply add each plugin to the versions section and synchronize our project. Then, we replace the elements within the plugins{} block of the build file with their catalog names.

For example:

plugins {
   id("com.android.application") version "7.4.1" apply false
}

becomes:

plugins {
   alias(libs.plugins.android.application) apply false
}

If we observe within our catalog, we can see that the implementation becomes more readable:

[versions]
androidGradlePlugin = "7.4.1"

[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }

As an additional note, in Google's official documentation for catalogs, if we use version 8.1 of Gradle, we must annotate the plugins{} block with the following attribute

@Suppress("DSL_SCOPE_VIOLATION").

We've just taken a glimpse of what version catalogs will be for our Android projects. It's interesting how functional they can become. To conclude, I emphasize that it's still a feature under active development, so there may be issues and limitations. For more information, you can consult the following documentation: link to documentation.

That's all! Regards.

TOML Language GitHub Repository:
Tom's Obvious, Minimal Language. (n.d.). GitHub. Retrieved from https://github.com/toml-lang

TOML Official Website:
Tom's Obvious, Minimal Language. (n.d.). TOML. Retrieved from https://toml.io/en/

Gradle Feature Documentation (in Spanish) - Known Issues with Version Catalogs:
Google. (n.d.). Android Studio Preview Features. Retrieved from https://developer.android.com/studio/preview/features?hl=es-419#gradle-version-catalogs-known-issues

Gradle Version Catalogs Migration Documentation (in Spanish):
Google. (n.d.). Migrate to Version Catalogs. Retrieved from https://developer.android.com/build/migrate-to-catalogs?hl=es-419