Version Catalogs in Gradle 7.0

Currently, there are multiple ways to share dependency versions between projects in multi-project builds. For example, users can declare versions or dependency coordinates directly in build scripts (in the ext block), external files (e.g dependencies.gradle), in buildSrc.

In version 7.0 Gradle has introduced an incubating feature to centrally manage dependencies in your Gradle project that tries to combine the advantages of both approaches.

Version Catalog enables build authors to centralize the dependency coordinates (group, artifact, version) of their third-party dependencies in a conventional configuration file and declare the actual dependencies in a type-safe way. Declaring dependencies this way allows easy reuse of dependency coordinates in all modules, provides content assistance in the IDEs, and reduces the risk of typos. More importantly, it also provides a single location to change versions when upgrading a library.

How to use the version catalog feature?

Version Catalog is an experimental feature hence opt-in is required.

Enable version catalog

To enable the feature to add the below line in your project’s settings.gradle(.kts)

Update: Version Catalog is stable in Gradle version 7.4, enabling feature is not required when using version 7.4 or above.

Creating a version catalog

A version catalog can be created in a couple of ways

• Declaring a catalog in the settings.gradle(.kts) file
• Declaring dependencies in a libs.versions.toml file

Declaring a catalog in the settings.gradle(.kts) file

The catalog can be created using the dependencyResolutionManagent API as shown below in the settings.gradle(.kts) file.

Declaring dependencies in a libs.versions.toml file

In addition to the settings API above, Gradle offers a conventional file to declare a catalog. If libs.versions.toml is found in the gradle subdirectory of the root build, then a catalog will be automatically declared with the contents of this file.

Create gradle/libs.versions.toml file from the root of your project as shown below

The version catalog TOML file format

The TOML file consists of 3 major sections:

• the [versions] section is used to declare versions which can be referenced by dependencies
• the [libraries] section is used to declare the aliases to coordinates
• the [bundles] section is used to declare dependency bundles

Declaring dependencies in the build.gradle file

Declaring dependency in the build.gralde does not change much, instead of mentioning the dependency name and version in the dependency block libs.<aliasName> or libs.bundles.<bundleName> is used.

Bundles is a list of dependency which needs is added to the application.

Advantages of using a version catalog

Version catalog has a number of advantages over declaring dependencies directly in the build script.

• For each catalog, Gradle generates type-safe accessors so that you can easily add dependencies with autocompletion in the IDE.
• Each catalog is visible to all projects of a build. It is a central place to declare a version of a dependency and to make sure that a change to that version applies to every subproject.
• Catalogs can declare dependency bundles, which are “groups of dependencies” that are commonly used together.
• Catalogs can separate the group and name of a dependency from its actual version and use version references instead, making it possible to share a version declaration between multiple dependencies.

Version Catalogs have a few advantages even above buildSrc approach or ext block.

• Version catalogs can be shared across teams or projects, as catalog files can be imported into a project using version catalog builder API.
• Version catalogs can be published using the maven-publish plugin making it easier to share across teams or in some cases outside the organisations.

Refer to official documentation to know more about Version Catalogs.