Gradle Version Catalogs provide a centralized way to manage dependencies and plugins across multiple Gradle projects. This guide covers implementation, best practices, and migration strategies.

---

Core Concepts

What is a Version Catalog?

• Centralized version declarations for dependencies and plugins
• Type-safe dependency references in build files
• Shared across multiple modules and projects
• Improves maintainability and consistency

Key Benefits:

• Single Source of Truth: One place for version management
• Type Safety: IDE support and refactoring capabilities
• Consistency: Ensures all modules use same versions
• Easy Updates: Update versions in one location

---

Implementation Guide

1. Version Catalog File Structure

# gradle/libs.versions.toml - Main version catalog file

[versions]

# Core dependencies spring-boot = "3.1.0" spring-cloud = "2022.0.3" jackson = "2.15.2" # Testing junit = "5.9.3" mockito = "5.3.1" testcontainers = "1.18.3" # Database h2 = "2.2.220" postgresql = "42.6.0" hibernate = "6.2.7.Final" # Utilities lombok = "1.18.28" mapstruct = "1.5.5.Final" guava = "32.1.1-jre" # Logging slf4j = "2.0.7" logback = "1.4.11" # Build plugins spotless = "6.19.0" jacoco = "0.8.10" git-properties = "2.4.1"

[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-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 Cloud spring-cloud-starter-config = { module = "org.springframework.cloud:spring-cloud-starter-config", version.ref = "spring-cloud" } spring-cloud-starter-bootstrap = { module = "org.springframework.cloud:spring-cloud-starter-bootstrap", version.ref = "spring-cloud" } # Database h2 = { module = "com.h2database:h2", version.ref = "h2" } postgresql = { module = "org.postgresql:postgresql", version.ref = "postgresql" } hibernate-core = { module = "org.hibernate.orm:hibernate-core", version.ref = "hibernate" } # Jackson 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" } # 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" } testcontainers-junit-jupiter = { module = "org.testcontainers:junit-jupiter", version.ref = "testcontainers" } testcontainers-postgresql = { module = "org.testcontainers:postgresql", version.ref = "testcontainers" } # Utilities 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" } guava = { module = "com.google.guava:guava", version.ref = "guava" } # Logging slf4j-api = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" } logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" } # Monitoring micrometer-core = { module = "io.micrometer:micrometer-core", version.ref = "micrometer" } micrometer-registry-prometheus = { module = "io.micrometer:micrometer-registry-prometheus", version.ref = "micrometer" }

[bundles]

# Predefined dependency groups spring-boot-web = ["spring-boot-starter-web", "spring-boot-starter-validation", "spring-boot-starter-actuator"] spring-data = ["spring-boot-starter-data-jpa", "hibernate-core"] testing = ["junit-jupiter", "mockito-core", "mockito-junit-jupiter", "spring-boot-starter-test"] database = ["postgresql", "h2"] logging = ["slf4j-api", "logback-classic"] monitoring = ["micrometer-core", "micrometer-registry-prometheus"]

[plugins]

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

2. Multi-Module Project Structure

project-root/ ├── gradle/ │ └── libs.versions.toml ├── build.gradle.kts ├── settings.gradle.kts ├── api/ │ └── build.gradle.kts ├── core/ │ └── build.gradle.kts ├── service/ │ └── build.gradle.kts └── infrastructure/ └── build.gradle.kts

3. Root build.gradle.kts

// build.gradle.kts - Root project plugins { // Plugins applied to root project only alias(libs.plugins.spotless) alias(libs.plugins.git.properties) } allprojects { group = "com.example" version = "1.0.0-SNAPSHOT" repositories { mavenCentral() mavenLocal() } } subprojects { apply(plugin = "java") apply(plugin = "jacoco") java { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 toolchain { languageVersion.set(JavaLanguageVersion.of(17)) } } tasks.withType<Test> { useJUnitPlatform() testLogging { events("passed", "skipped", "failed") } } // Configure JaCoCo for test coverage jacoco { toolVersion = libs.versions.jacoco.get() } tasks.jacocoTestReport { dependsOn(tasks.test) reports { xml.required.set(true) html.required.set(true) csv.required.set(false) } } } // Spotless configuration for code formatting spotless { java { target("**/*.java") googleJavaFormat(libs.versions.spotless.get()) removeUnusedImports() trimTrailingWhitespace() endWithNewline() } kotlin { target("**/*.kt") ktlint(libs.versions.spotless.get()) trimTrailingWhitespace() endWithNewline() } } // Git properties for Spring Boot Actuator gitProperties { keys = listOf("git.branch", "git.commit.id", "git.commit.time") } // Task to display dependency updates tasks.register("dependencyUpdates") { doLast { println("=== Dependency Versions ===") libs.versions.forEach { (key, version) -> println("$key: ${version.get()}") } } }

4. Settings.gradle.kts

// settings.gradle.kts rootProject.name = "my-application" // Enable version catalog enableFeaturePreview("VERSION_CATALOGS") // Include subprojects include(":api") include(":core") include(":service") include(":infrastructure") include(":shared:utils") include(":shared:models") // Dependency resolution rules dependencyResolutionManagement { // Use version catalog versionCatalogs { create("libs") { from(files("gradle/libs.versions.toml")) } } repositories { mavenCentral() gradlePluginPortal() } }

5. Module build.gradle.kts Examples

API Module:

// api/build.gradle.kts plugins { alias(libs.plugins.spring.boot) alias(libs.plugins.spring.dependency.management) } dependencies { // Spring Boot bundles implementation(platform(libs.spring.boot.get().toString())) implementation(libs.bundles.spring.boot.web) // Project modules implementation(project(":core")) implementation(project(":shared:utils")) // Database implementation(libs.bundles.database) // Monitoring implementation(libs.bundles.monitoring) // Testing testImplementation(libs.bundles.testing) testImplementation(libs.testcontainers.postgresql) } springBoot { buildInfo() }

Core Module:

// core/build.gradle.kts plugins { id("java-library") } dependencies { // Spring Data api(libs.bundles.spring.data) // Utilities compileOnly(libs.lombok) annotationProcessor(libs.lombok) implementation(libs.mapstruct) annotationProcessor(libs.mapstruct.processor) implementation(libs.guava) // Jackson for JSON processing implementation(libs.jackson.databind) implementation(libs.jackson.datatype.jsr310) // Testing testImplementation(libs.bundles.testing) testImplementation(libs.testcontainers.postgresql) testRuntimeOnly(libs.h2) } tasks.withType<JavaCompile> { options.compilerArgs.addAll(listOf( "-Amapstruct.defaultComponentModel=spring" )) }

Service Module:

// service/build.gradle.kts plugins { id("java-library") } dependencies { // Project modules api(project(":core")) implementation(project(":shared:models")) // Spring implementation(libs.spring.boot.starter.validation) // Utilities compileOnly(libs.lombok) annotationProcessor(libs.lombok) implementation(libs.mapstruct) annotationProcessor(libs.mapstruct.processor) // Testing testImplementation(libs.bundles.testing) testImplementation(libs.spring.boot.starter.test) }

Infrastructure Module:

// infrastructure/build.gradle.kts plugins { id("java-library") alias(libs.plugins.spring.boot) } dependencies { // Project modules implementation(project(":core")) implementation(project(":service")) // Spring Cloud Config implementation(libs.spring.cloud.starter.config) implementation(libs.spring.cloud.starter.bootstrap) // External services clients implementation(libs.bundles.spring.boot.web) // Resilience implementation("io.github.resilience4j:resilience4j-spring-boot2:2.0.2") implementation("io.github.resilience4j:resilience4j-circuitbreaker:2.0.2") // Testing testImplementation(libs.bundles.testing) testImplementation(libs.testcontainers.junit.jupiter) }

Shared Utils Module:

// shared/utils/build.gradle.kts plugins { id("java-library") } dependencies { // Minimal dependencies for utility classes implementation(libs.slf4j.api) implementation(libs.guava) compileOnly(libs.lombok) annotationProcessor(libs.lombok) // Testing testImplementation(libs.junit.jupiter) testImplementation(libs.mockito.core) }

6. Custom Version Catalog for Internal Libraries

# gradle/internal.versions.toml - For internal/company libraries

[versions]

company-commons = "2.3.0" company-security = "1.5.0" company-monitoring = "3.1.0"

[libraries]

company-commons-core = { module = "com.company:commons-core", version.ref = "company-commons" } company-commons-utils = { module = "com.company:commons-utils", version.ref = "company-commons" } company-security-core = { module = "com.company:security-core", version.ref = "company-security" } company-monitoring-client = { module = "com.company:monitoring-client", version.ref = "company-monitoring" }

[bundles]

company-commons = ["company-commons-core", "company-commons-utils"] company-security = ["company-security-core"] company-monitoring = ["company-monitoring-client"]

Update settings.gradle.kts to include internal catalog:

dependencyResolutionManagement { versionCatalogs { create("libs") { from(files("gradle/libs.versions.toml")) } create("companyLibs") { from(files("gradle/internal.versions.toml")) } } }

Usage in build files:

dependencies { implementation(companyLibs.bundles.company.commons) implementation(companyLibs.bundles.company.security) }

7. Advanced Version Catalog Features

Platform Definitions:

// platform/build.gradle.kts - For BOM-style dependency management plugins { `java-platform` } dependencies { constraints { // Define all versions as constraints api(libs.spring.boot.get()) api(libs.spring.cloud.get()) api(libs.junit.get()) // ... more constraints } }

Custom Catalog Access in Build Scripts:

// Accessing version catalog programmatically tasks.register("printDependencyVersions") { doLast { println("=== Spring Boot Version ===") println(libs.versions.spring.boot.get()) println("=== All Libraries ===") libs.libraries.forEach { (name, dependency) -> println("$name: ${dependency.version}") } println("=== Testing Bundle ===") val testingBundle = libs.bundles.testing.get() testingBundle.forEach { dependency -> println(" - ${dependency.name}: ${dependency.version}") } } }

Conditional Dependencies:

// Conditional dependency based on profile val profile: String by project dependencies { if (profile == "dev") { implementation(libs.h2) } else { implementation(libs.postgresql) } }

8. Migration Script from build.gradle

Before (Traditional build.gradle):

// build.gradle (old style) dependencies { implementation 'org.springframework.boot:spring-boot-starter-web:3.1.0' implementation 'org.springframework.boot:spring-boot-starter-data-jpa:3.1.0' implementation 'org.postgresql:postgresql:42.6.0' implementation 'org.projectlombok:lombok:1.18.28' annotationProcessor 'org.projectlombok:lombok:1.18.28' testImplementation 'org.junit.jupiter:junit-jupiter:5.9.3' testImplementation 'org.mockito:mockito-core:5.3.1' testImplementation 'org.springframework.boot:spring-boot-starter-test:3.1.0' }

After (Version Catalog):

// build.gradle.kts (with version catalog) dependencies { implementation(libs.bundles.spring.boot.web) implementation(libs.bundles.spring.data) implementation(libs.postgresql) compileOnly(libs.lombok) annotationProcessor(libs.lombok) testImplementation(libs.bundles.testing) }

9. Dependency Verification

// build.gradle.kts - Dependency verification configuration dependencyVerification { verifyConfig = true // Verify checksums for dependencies checksums = mapOf( "sha256" to listOf("warn", "fail-on-missing"), "sha512" to listOf("warn") ) } // Task to validate dependency consistency tasks.register("validateDependencies") { doLast { val catalog = the<VersionCatalogsExtension>().named("libs") // Check for duplicate dependencies val libraries = catalog.libraryNames val duplicates = libraries.groupBy { it }.filter { it.value.size > 1 } if (duplicates.isNotEmpty()) { throw GradleException("Duplicate libraries found: $duplicates") } // Validate version consistency catalog.libraryAliases.forEach { alias -> val library = catalog.findLibrary(alias).get().get() println("Validating: $alias -> ${library.module}:${library.version}") } println("Dependency validation completed successfully!") } }

10. Custom Tasks for Version Management

// Version management tasks tasks.register("updateDependency", UpdateDependency::class) { group = "versioning" description = "Update a specific dependency version" } abstract class UpdateDependency : DefaultTask() { @Option(option = "dependency", description = "Dependency to update") var dependency: String = "" @Option(option = "version", description = "New version") var newVersion: String = "" @TaskAction fun update() { if (dependency.isBlank() || newVersion.isBlank()) { throw GradleException("Both --dependency and --version are required") } val catalogFile = project.file("gradle/libs.versions.toml") val content = catalogFile.readText() // Simple string replacement - in real implementation, use proper TOML parser val updatedContent = content.replace( "$dependency = \"[^\"]*\"".toRegex(), "$dependency = \"$newVersion\"" ) catalogFile.writeText(updatedContent) println("Updated $dependency to version $newVersion") } } // Task to generate dependency report tasks.register("dependencyReport", DependencyReport::class) { group = "reporting" description = "Generate comprehensive dependency report" } abstract class DependencyReport : DefaultTask() { @OutputFile val reportFile = project.layout.buildDirectory.file("reports/dependencies.md") @TaskAction fun generate() { val catalog = the<VersionCatalogsExtension>().named("libs") val report = buildString { appendLine("# Dependency Report") appendLine() appendLine("## Versions") catalog.versionAliases.forEach { alias -> appendLine("- **$alias**: ${catalog.findVersion(alias).get().get()}") } appendLine() appendLine("## Libraries") catalog.libraryAliases.forEach { alias -> val library = catalog.findLibrary(alias).get().get() appendLine("- **$alias**: ${library.module}:${library.version}") } appendLine() appendLine("## Bundles") catalog.bundleAliases.forEach { alias -> appendLine("- **$alias**:") catalog.findBundle(alias).get().get().forEach { dependency -> appendLine(" - ${dependency.name}: ${dependency.version}") } } } reportFile.get().asFile.writeText(report) println("Dependency report generated: ${reportFile.get().asFile}") } }

11. Integration with CI/CD

# .github/workflows/dependency-check.yml name: Dependency Check on: schedule: - cron: '0 0 * * 1' # Weekly push: branches: [ main ] jobs: dependency-updates: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up JDK 17 uses: actions/setup-java@v3 with: java-version: '17' distribution: 'temurin' - name: Check for dependency updates run: ./gradlew dependencyUpdates -Drevision=release - name: Validate dependencies run: ./gradlew validateDependencies

12. Best Practices and Conventions

Naming Conventions:

# Good naming practices

[versions]

spring-boot = "3.1.0" # kebab-case for versions jackson = "2.15.2"

[libraries]

spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" } jackson-databind = { module = "com.fasterxml.jackson.core:jackson-databind", version.ref = "jackson" }

[bundles]

spring-boot-web = ["spring-boot-starter-web", "spring-boot-starter-validation"] testing = ["junit-jupiter", "mockito-core", "spring-boot-starter-test"]

Organization Strategies:

# Organize by domain/functionality

[versions]

# Core framework spring-boot = "3.1.0" # Database database-hibernate = "6.2.7" # Testing testing-junit = "5.9.3" # Group libraries by domain

[libraries]

# Web spring-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" } # Data spring-data-jpa = { module = "org.springframework.boot:spring-boot-starter-data-jpa", version.ref = "spring-boot" } hibernate-core = { module = "org.hibernate.orm:hibernate-core", version.ref = "database-hibernate" } # Testing junit-api = { module = "org.junit.jupiter:junit-jupiter-api", version.ref = "testing-junit" }

---

Migration Strategy

1. Start Small: Begin with a single module
2. Incremental Migration: Convert one dependency group at a time
3. Validation: Use dependency validation tasks
4. Team Training: Ensure team understands new syntax
5. CI Integration: Add validation to CI pipeline

// Migration helper task tasks.register("migrateDependencies") { doLast { println(""" Migration Steps: 1. Create gradle/libs.versions.toml 2. Move versions to [versions] section 3. Define libraries in [libraries] section 4. Create bundles for common groups 5. Update build.gradle.kts files 6. Test the build 7. Remove old version declarations """.trimIndent()) } }

---

Conclusion

Gradle Version Catalogs provide:

• Centralized Management: Single source of truth for dependencies
• Type Safety: IDE support and compile-time safety
• Consistency: Uniform versions across projects
• Maintainability: Easy updates and refactoring
• Scalability: Suitable for large multi-module projects

By implementing version catalogs, you can significantly improve dependency management, reduce version conflicts, and streamline your build configuration across multiple Java projects.