MACRO NEPAL
Mastering Dependency Management: Gradle Version Catalog in Java
awiskar acharya
November 18, 2025
8:57 am

Gradle Version Catalog is a powerful feature that allows you to centralize dependency versions, plugins, and libraries across multiple modules and projects. It provides type-safe dependency declarations, improves build consistency, and simplifies dependency management in large Java projects.

What is Gradle Version Catalog?

Version Catalog enables you to:

  • Define dependencies centrally in a single location
  • Share versions across multiple modules
  • Enable type-safe access in build scripts
  • Improve maintainability of dependency declarations
  • Standardize dependency names across teams

Traditional vs Version Catalog Approach

Traditional:
// app/build.gradle
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web:3.2.0'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa:3.2.0'
testImplementation 'org.springframework.boot:spring-boot-starter-test:3.2.0'
}
Version Catalog:
// app/build.gradle
dependencies {
implementation libs.spring.boot.starter.web
implementation libs.spring.boot.starter.data.jpa
testImplementation libs.spring.boot.starter.test
}

Hands-On Tutorial: Implementing Gradle Version Catalog

Let's build a complete multi-module Java project with comprehensive version catalog configuration.

Step 1: Project Structure Setup

multi-module-project/
├── gradle/
│   └── libs.versions.toml          # Version catalog definition
├── build-logic/
│   ├── build.gradle.kts
│   └── src/main/groovy/
│       └── java-common-conventions.gradle
├── core/
│   └── build.gradle.kts
├── service/
│   └── build.gradle.kts
├── web/
│   └── build.gradle.kts
├── build.gradle.kts
└── settings.gradle.kts

Step 2: Version Catalog Definition

gradle/libs.versions.toml:

[versions]
# Spring Boot
spring-boot = "3.2.0"
spring-dependency-management = "1.1.4"
# Spring Framework
spring-core = "6.1.1"
spring-context = "6.1.1"
spring-data-jpa = "3.2.0"
spring-security = "6.2.0"
# Database
hibernate = "6.4.1"
postgresql = "42.7.1"
h2 = "2.2.224"
flyway = "10.5.0"
# Testing
junit = "5.10.1"
mockito = "5.8.0"
assertj = "3.24.2"
testcontainers = "1.19.3"
# Logging
slf4j = "2.0.9"
logback = "1.4.14"
# JSON
jackson = "2.16.1"
# HTTP Client
okhttp = "4.12.0"
retrofit = "2.9.0"
# Monitoring
micrometer = "1.12.0"
micrometer-tracing = "1.2.0"
# Utilities
guava = "32.1.3-jre"
apache-commons = "3.14.0"
vavr = "0.10.4"
# Build Tools
lombok = "1.18.30"
mapstruct = "1.5.5.Final"
# Code Quality
spotless = "6.23.0"
checkstyle = "10.12.5"
pmd = "6.55.0"
jacoco = "0.8.11"

[libraries]

# Spring Boot spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" } spring-boot-starter-data-jpa = { module = "org.springframework.boot:spring-boot-starter-data-jpa", version.ref = "spring-boot" } spring-boot-starter-security = { module = "org.springframework.boot:spring-boot-starter-security", version.ref = "spring-boot" } spring-boot-starter-validation = { module = "org.springframework.boot:spring-boot-starter-validation", version.ref = "spring-boot" } spring-boot-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator", version.ref = "spring-boot" } spring-boot-starter-test = { module = "org.springframework.boot:spring-boot-starter-test", version.ref = "spring-boot" } # Spring Framework spring-core = { module = "org.springframework:spring-core", version.ref = "spring-core" } spring-context = { module = "org.springframework:spring-context", version.ref = "spring-context" } spring-data-jpa = { module = "org.springframework.data:spring-data-jpa", version.ref = "spring-data-jpa" } # Database hibernate-core = { module = "org.hibernate.orm:hibernate-core", version.ref = "hibernate" } postgresql = { module = "org.postgresql:postgresql", version.ref = "postgresql" } h2 = { module = "com.h2database:h2", version.ref = "h2" } flyway-core = { module = "org.flywaydb:flyway-core", version.ref = "flyway" } # Testing junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" } junit-jupiter-api = { module = "org.junit.jupiter:junit-jupiter-api", version.ref = "junit" } junit-jupiter-engine = { module = "org.junit.jupiter:junit-jupiter-engine", version.ref = "junit" } mockito-core = { module = "org.mockito:mockito-core", version.ref = "mockito" } mockito-junit-jupiter = { module = "org.mockito:mockito-junit-jupiter", version.ref = "mockito" } assertj-core = { module = "org.assertj:assertj-core", version.ref = "assertj" } testcontainers-junit-jupiter = { module = "org.testcontainers:junit-jupiter", version.ref = "testcontainers" } testcontainers-postgresql = { module = "org.testcontainers:postgresql", version.ref = "testcontainers" } # Logging slf4j-api = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" } logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" } # JSON jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" } jackson-datatype-jsr310 = { module = "com.fasterxml.jackson.datatype:jackson-datatype-jsr310", version.ref = "jackson" } # HTTP Client okhttp = { module = "com.squareup.okhttp3:okhttp", version.ref = "okhttp" } retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" } # Monitoring micrometer-core = { module = "io.micrometer:micrometer-core", version.ref = "micrometer" } micrometer-registry-prometheus = { module = "io.micrometer:micrometer-registry-prometheus", version.ref = "micrometer" } micrometer-tracing = { module = "io.micrometer:micrometer-tracing", version.ref = "micrometer-tracing" } # Utilities guava = { module = "com.google.guava:guava", version.ref = "guava" } apache-commons-lang3 = { module = "org.apache.commons:commons-lang3", version.ref = "apache-commons" } vavr = { module = "io.vavr:vavr", version.ref = "vavr" } # Build Tools lombok = { module = "org.projectlombok:lombok", version.ref = "lombok" } mapstruct = { module = "org.mapstruct:mapstruct", version.ref = "mapstruct" } mapstruct-processor = { module = "org.mapstruct:mapstruct-processor", version.ref = "mapstruct" } # Code Quality spotless-plugin-gradle = { module = "com.diffplug.spotless:spotless-plugin-gradle", version.ref = "spotless" }

[plugins]

spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" } spring-dependency-management = { id = "io.spring.dependency-management", version.ref = "spring-dependency-management" } jacoco = { id = "com.diffplug.gradle.spotless", version.ref = "jacoco" }

[bundles]

# Common dependency bundles spring-web = ["spring-boot-starter-web", "spring-boot-starter-validation"] spring-data = ["spring-boot-starter-data-jpa", "hibernate-core"] testing = ["junit-jupiter", "mockito-core", "assertj-core", "mockito-junit-jupiter"] monitoring = ["micrometer-core", "micrometer-registry-prometheus", "micrometer-tracing"] database = ["postgresql", "flyway-core", "h2"]

[metadata]

format.version = "1.1"

Step 3: Settings Configuration

settings.gradle.kts:

rootProject.name = "multi-module-project"
// Enable version catalog
enableFeaturePreview("VERSION_CATALOGS")
// Define version catalog
dependencyResolutionManagement {
versionCatalogs {
create("libs") {
from(files("gradle/libs.versions.toml"))
}
}
}
// Include build logic
includeBuild("build-logic")
// Project modules
include(":core")
include(":service") 
include(":web")
include(":integration-tests")
project(":core").projectDir = file("core")
project(":service").projectDir = file("service")
project(":web").projectDir = file("web")
project(":integration-tests").projectDir = file("integration-tests")

Step 4: Build Logic Convention Plugin

build-logic/build.gradle.kts:

plugins {
`groovy-gradle-plugin`
}
repositories {
gradlePluginPortal()
mavenCentral()
}
dependencies {
implementation(libs.plugins.spring.boot.get().toString())
implementation(libs.plugins.spring.dependency.management.get().toString())
implementation(libs.plugins.jacoco.get().toString())
}

build-logic/src/main/groovy/java-common-conventions.gradle.kts:

plugins {
java
jacoco
checkstyle
}
repositories {
mavenCentral()
}
java {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
withSourcesJar()
withJavadocJar()
}
dependencies {
// Common dependencies for all Java modules
implementation(libs.slf4j.api)
implementation(libs.apache.commons.lang3)
// Testing bundle
testImplementation(libs.bundles.testing)
}
tasks.withType<Test> {
useJUnitPlatform()
testLogging {
events("passed", "failed", "skipped")
setExceptionFormat("full")
}
finalizedBy(tasks.jacocoTestReport)
}
tasks.jacocoTestReport {
dependsOn(tasks.test)
reports {
xml.required.set(true)
html.required.set(true)
csv.required.set(false)
}
}
checkstyle {
toolVersion = libs.versions.checkstyle.get()
configFile = rootProject.file("config/checkstyle/checkstyle.xml")
isIgnoreFailures = false
maxErrors = 0
maxWarnings = 0
}
tasks.withType<Checkstyle> {
reports {
xml.required.set(false)
html.required.set(true)
}
}

Step 5: Root Build Configuration

build.gradle.kts:

plugins {
id("java-common-conventions")
}
allprojects {
group = "com.example"
version = "1.0.0-SNAPSHOT"
repositories {
mavenCentral()
maven { url = uri("https://repo.spring.io/milestone") }
}
}
subprojects {
apply(plugin = "java-common-conventions")
dependencies {
// Common dependencies for all subprojects
constraints {
implementation(libs.guava)
implementation(libs.vavr)
}
}
}
// Code quality tasks
tasks.register("codeQuality") {
group = "verification"
description = "Runs all code quality checks"
dependsOn(subprojects.map { it.tasks.named("check") })
}
tasks.register("testAll") {
group = "verification"
description = "Runs tests in all modules"
dependsOn(subprojects.map { it.tasks.named("test") })
}
// JaCoCo aggregate report
tasks.register<JacocoReport>("jacocoRootReport") {
group = "verification"
description = "Generates an aggregate code coverage report"
executionData(fileTree(project.rootDir.absolutePath).include("**/build/jacoco/*.exec"))
subprojects.forEach { subproject ->
subproject.plugins.withType<JacocoPlugin>().configureEach {
subproject.the<JacocoPluginExtension>().apply {
subproject.tasks.matching { it.extensions.findByType<JacocoTaskExtension>() != null }
.configureEach { sourceDirectories.from(files(classDirectories)) }
classDirectories.from(files(classDirectories))
}
}
}
reports {
html.required.set(true)
xml.required.set(true)
csv.required.set(false)
}
}

Step 6: Core Module Configuration

core/build.gradle.kts:

plugins {
id("java-library")
}
description = "Core domain models and business logic"
dependencies {
api(libs.spring.core)
api(libs.spring.context)
implementation(libs.hibernate.core)
implementation(libs.jackson.databind)
implementation(libs.jackson.datatype.jsr310)
// Annotation processors
compileOnly(libs.lombok)
annotationProcessor(libs.lombok)
compileOnly(libs.mapstruct)
annotationProcessor(libs.mapstruct.processor)
// Test dependencies
testImplementation(libs.testcontainers.junit.jupiter)
testImplementation(libs.testcontainers.postgresql)
}
tasks.jar {
manifest {
attributes(
"Implementation-Title" to project.name,
"Implementation-Version" to project.version
)
}
}

Step 7: Service Module Configuration

service/build.gradle.kts:

plugins {
id("java-library")
id("org.springframework.boot") apply false
id("io.spring.dependency-management")
}
description = "Business service layer implementation"
dependencyManagement {
imports {
mavenBom(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
}
}
dependencies {
api(project(":core"))
implementation(libs.bundles.spring.data)
implementation(libs.bundles.monitoring)
implementation(libs.bundles.database)
implementation(libs.spring.boot.starter.actuator)
implementation(libs.spring.boot.starter.validation)
// Annotation processors
compileOnly(libs.lombok)
annotationProcessor(libs.lombok)
// Runtime dependencies
runtimeOnly(libs.postgresql)
runtimeOnly(libs.h2)
// Test dependencies
testImplementation(libs.spring.boot.starter.test)
testImplementation(libs.bundles.testing)
testRuntimeOnly(libs.logback.classic)
}
tasks.test {
useJUnitPlatform()
systemProperty("spring.profiles.active", "test")
}

Step 8: Web Module Configuration

web/build.gradle.kts:

plugins {
id("java")
id("org.springframework.boot")
id("io.spring.dependency-management")
}
description = "Web layer with REST API"
dependencies {
implementation(project(":core"))
implementation(project(":service"))
implementation(libs.bundles.spring.web)
implementation(libs.spring.boot.starter.security)
implementation(libs.spring.boot.starter.actuator)
implementation(libs.bundles.monitoring)
implementation(libs.okhttp)
implementation(libs.retrofit)
// Annotation processors
compileOnly(libs.lombok)
annotationProcessor(libs.lombok)
compileOnly(libs.mapstruct)
annotationProcessor(libs.mapstruct.processor)
// Test dependencies
testImplementation(libs.spring.boot.starter.test)
testImplementation(libs.bundles.testing)
testImplementation(libs.spring.security.test)
}
springBoot {
buildInfo()
}
tasks.bootJar {
manifest {
attributes(
"Start-Class" to "com.example.web.Application",
"Spring-Boot-Version" to libs.versions.spring.boot.get()
)
}
}
tasks.test {
useJUnitPlatform()
maxHeapSize = "2G"
}

Step 9: Integration Tests Module

integration-tests/build.gradle.kts:

plugins {
id("java")
}
description = "Integration tests module"
dependencies {
implementation(project(":web"))
implementation(project(":service"))
implementation(libs.spring.boot.starter.web)
implementation(libs.spring.boot.starter.test)
implementation(libs.bundles.testing)
implementation(libs.testcontainers.junit.jupiter)
implementation(libs.testcontainers.postgresql)
testImplementation(libs.spring.security.test)
}
tasks.test {
useJUnitPlatform()
systemProperty("spring.profiles.active", "integration-test")
testLogging {
events("passed", "failed", "skipped")
showStandardStreams = true
}
}

Step 10: Custom Version Catalog Extensions

gradle/dependencies.gradle.kts:

import org.gradle.accessors.dm.LibrariesForLibs
// Extension functions for common dependency patterns
val LibrariesForLibs.`spring-boot-bom` get() = plugins.spring.boot.get()
fun LibrariesForLibs.springBootStarter(starter: String) = 
library("spring-boot-starter-$starter", "org.springframework.boot:spring-boot-starter-$starter")
fun LibrariesForLibs.testingBundle() = bundles.testing
fun LibrariesForLibs.databaseBundle() = bundles.database
// Version accessors
val LibrariesForLibs.javaVersion get() = JavaVersion.VERSION_17
// Dependency constraints helper
fun DependencyHandler.constraints(configure: DependencyConstraintHandler.() -> Unit) {
(this as ExtensionAware).extensions.configure("constraints", configure)
}

Step 11: Advanced Version Catalog with Plugins

gradle/plugins.versions.toml:

[versions]
spring-boot = "3.2.0"
jacoco = "0.8.11"
spotless = "6.23.0"
sonarqube = "4.4.1.3373"
git-properties = "2.4.1"
docker = "9.4.0"

[plugins]

spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" } spring-dependency-management = { id = "io.spring.dependency-management", version = "1.1.4" } jacoco = { id = "jacoco", version.ref = "jacoco" } spotless = { id = "com.diffplug.spotless", version.ref = "spotless" } sonarqube = { id = "org.sonarqube", version.ref = "sonarqube" } git-properties = { id = "com.gorylenko.gradle-git-properties", version.ref = "git-properties" } docker = { id = "com.bmuschko.docker-spring-boot-application", version.ref = "docker" }

Step 12: Build Script Using Version Catalog

build.gradle.kts (using extensions):

plugins {
alias(libs.plugins.spring.boot) apply false
alias(libs.plugins.spring.dependency.management) apply false
alias(libs.plugins.jacoco)
alias(libs.plugins.spotless)
alias(libs.plugins.sonarqube)
}
apply(from = "gradle/dependencies.gradle.kts")
allprojects {
apply(plugin = "jacoco")
apply(plugin = "com.diffplug.spotless")
spotless {
java {
target("src/**/*.java")
googleJavaFormat(libs.versions.spotless.get())
removeUnusedImports()
trimTrailingWhitespace()
endWithNewline()
}
kotlin {
target("src/**/*.kt")
ktlint(libs.versions.spotless.get())
trimTrailingWhitespace()
endWithNewline()
}
}
}
sonarqube {
properties {
property("sonar.projectKey", "multi-module-project")
property("sonar.host.url", "http://localhost:9000")
property("sonar.coverage.jacoco.xmlReportPaths", "build/reports/jacoco/jacocoRootReport/jacocoRootReport.xml")
}
}
// Custom task for dependency updates
tasks.register("dependencyUpdates", com.github.benmanes.gradle.versions.tasks.DependencyUpdatesTask::class) {
group = "help"
description = "Displays dependency updates"
resolutionStrategy {
componentSelection {
all {
if (isNonStable(candidate.version) && !isNonStable(currentVersion)) {
reject("Release candidate")
}
}
}
}
outputFormatter = "html"
outputDir = "build/dependencyUpdates"
}
fun isNonStable(version: String): Boolean {
val stableKeyword = listOf("RELEASE", "FINAL", "GA").any { version.uppercase().contains(it) }
val regex = "^[0-9,.v-]+(-r)?$".toRegex()
val isStable = stableKeyword || regex.matches(version)
return !isStable
}

Step 13: Domain Models (Example Usage)

core/src/main/java/com/example/core/domain/Product.java:

package com.example.core.domain;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import javax.persistence.*;
import java.math.BigDecimal;
import java.time.LocalDateTime;
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Table(name = "products")
public class Product {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, unique = true)
private String sku;
@Column(nullable = false)
private String name;
private String description;
@Column(nullable = false)
private BigDecimal price;
private Integer stockQuantity;
@Enumerated(EnumType.STRING)
private ProductStatus status;
@Column(nullable = false)
private LocalDateTime createdAt;
private LocalDateTime updatedAt;
@PrePersist
protected void onCreate() {
createdAt = LocalDateTime.now();
}
@PreUpdate
protected void onUpdate() {
updatedAt = LocalDateTime.now();
}
public enum ProductStatus {
ACTIVE, INACTIVE, DISCONTINUED
}
}

Step 14: Service Implementation

service/src/main/java/com/example/service/ProductService.java:

package com.example.service;
import com.example.core.domain.Product;
import com.example.core.repository.ProductRepository;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.List;
import java.util.Optional;
@Slf4j
@Service
@RequiredArgsConstructor
@Transactional
public class ProductService {
private final ProductRepository productRepository;
public Product createProduct(Product product) {
log.info("Creating product: {}", product.getSku());
return productRepository.save(product);
}
@Transactional(readOnly = true)
public Optional<Product> getProductById(Long id) {
return productRepository.findById(id);
}
@Transactional(readOnly = true)
public List<Product> getAllActiveProducts() {
return productRepository.findByStatus(Product.ProductStatus.ACTIVE);
}
public Product updateProduct(Long id, Product productDetails) {
return productRepository.findById(id)
.map(existingProduct -> {
existingProduct.setName(productDetails.getName());
existingProduct.setDescription(productDetails.getDescription());
existingProduct.setPrice(productDetails.getPrice());
existingProduct.setStockQuantity(productDetails.getStockQuantity());
return productRepository.save(existingProduct);
})
.orElseThrow(() -> new ProductNotFoundException("Product not found with id: " + id));
}
public void deleteProduct(Long id) {
productRepository.deleteById(id);
log.info("Deleted product with id: {}", id);
}
public static class ProductNotFoundException extends RuntimeException {
public ProductNotFoundException(String message) {
super(message);
}
}
}

Step 15: Running the Build

Build commands:

# Build all modules
./gradlew build
# Run tests with coverage
./gradlew testAll jacocoRootReport
# Check code quality
./gradlew codeQuality
# Check for dependency updates
./gradlew dependencyUpdates
# Build specific module
./gradlew :web:build
# Run spotless formatting
./gradlew spotlessApply
# Sonar analysis
./gradlew sonarqube

Step 16: CI/CD Integration

.github/workflows/build.yml:

name: Java CI with Gradle
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up JDK 17
uses: actions/setup-java@v4
with:
java-version: '17'
distribution: 'temurin'
cache: 'gradle'
- name: Build with Gradle
run: ./gradlew build
- name: Run tests with coverage
run: ./gradlew testAll jacocoRootReport
- name: Code quality checks
run: ./gradlew codeQuality
- name: Upload coverage reports
uses: codecov/codecov-action@v3
with:
file: ./build/reports/jacoco/jacocoRootReport/jacocoRootReport.xml

Best Practices

1. Naming Conventions

# Good naming
spring-boot-starter-web = "org.springframework.boot:spring-boot-starter-web"
jackson-databind = "com.fasterxml.jackson.core:jackson-databind"
# Avoid
web = "org.springframework.boot:spring-boot-starter-web"  # Too vague
jackson = "com.fasterxml.jackson.core:jackson-databind"   # Ambiguous

2. Organization Strategies

  • Group by functionality: spring, database, testing, etc.
  • Use bundles for commonly used dependency groups
  • Separate versions from library definitions
  • Use meaningful aliases that match library names

3. Maintenance Tips

  • Regularly update versions using dependencyUpdates
  • Use version ranges cautiously in libraries
  • Document major version changes
  • Test thoroughly after version updates

Benefits of Version Catalog

  1. Centralized Management: Single source of truth for dependencies
  2. Type Safety: IDE support and compile-time checking
  3. Consistency: Uniform dependency declarations across modules
  4. Maintainability: Easy version updates and dependency changes
  5. Team Collaboration: Standardized dependency naming

Conclusion

Gradle Version Catalog transforms dependency management in Java projects by providing:

  • Centralized version control across multiple modules
  • Type-safe dependency declarations with IDE support
  • Consistent dependency naming conventions
  • Improved maintainability through bundles and conventions
  • Better team collaboration with standardized approaches

By implementing Version Catalog in your Java projects, you can significantly reduce build configuration complexity, prevent version conflicts, and create a more maintainable and scalable build system that grows with your project's needs.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper