gradle-dependency-management

Original：🇺🇸 English
Translated

Manages Gradle dependencies using version catalogs, BOMs, and dependency constraints. Use when setting up dependency management, centralizing versions, resolving conflicts, or configuring multi-module dependency sharing. Triggers on "setup version catalog", "centralize dependencies", "resolve version conflict", or "configure Gradle BOM". Works with gradle/libs.versions.toml and includes Bill of Materials, dependency constraints, and Spring Boot/GCP BOM integration.

10installs
Sourcedawiddutoit/custom-claude
Added on

NPX Install

npx skill4agent add dawiddutoit/custom-claude gradle-dependency-management

Tags

Translated version includes tags in frontmatter
gradle-dependency-managementversion-catalogsbom-integrationmulti-module-buildsdependency-conflict-resolution

SKILL.md Content

View Translation Comparison →

Gradle Dependency Management

Table of Contents

Purpose

Centralize and manage dependencies effectively across Gradle projects using version catalogs, BOMs, and dependency constraints. This skill helps you standardize versions, resolve conflicts, and maintain security across multi-module builds.

When to Use

Use this skill when you need to:
  • Centralize dependency versions across multi-module projects
  • Create type-safe dependency references with version catalogs
  • Resolve dependency version conflicts
  • Enforce consistent dependency versions across a team
  • Integrate Spring Boot or GCP BOMs for curated dependency sets
  • Lock dependency versions for reproducible builds
  • Manage transitive dependencies with constraints

Quick Start

Create a version catalog in 
gradle/libs.versions.toml
:
toml
[versions]
spring-boot = "3.5.5"
junit = "5.11.0"

[libraries]
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

[bundles]
spring-boot-web = ["spring-boot-starter-web"]
testing = ["junit-jupiter"]

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }
Configure in 
settings.gradle.kts
:
kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}
Use in 
build.gradle.kts
:
kotlin
plugins {
    alias(libs.plugins.spring.boot)
}

dependencies {
    implementation(libs.spring.boot.starter.web)
    testImplementation(libs.bundles.testing)
}

Instructions

Step 1: Set Up Version Catalog

Create 
gradle/libs.versions.toml
with your project's dependencies:
toml
[versions]
spring-boot = "3.5.5"
spring-cloud = "2024.0.1"
spring-cloud-gcp = "6.1.1"
mapstruct = "1.6.3"
testcontainers = "1.21.0"
junit = "5.11.0"
mockito = "5.14.0"

[libraries]
# Spring Boot
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }
spring-boot-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator" }
spring-boot-starter-data-jpa = { module = "org.springframework.boot:spring-boot-starter-data-jpa" }
spring-boot-starter-test = { module = "org.springframework.boot:spring-boot-starter-test" }

# GCP
spring-cloud-gcp-starter = { module = "com.google.cloud:spring-cloud-gcp-starter" }
spring-cloud-gcp-pubsub = { module = "com.google.cloud:spring-cloud-gcp-starter-pubsub" }
google-cloud-secretmanager = { module = "com.google.cloud:google-cloud-secretmanager", version = "2.2.0" }

# Database
postgresql = { module = "org.postgresql:postgresql" }
flyway-core = { module = "org.flywaydb:flyway-core" }

# MapStruct
mapstruct = { module = "org.mapstruct:mapstruct", version.ref = "mapstruct" }
mapstruct-processor = { module = "org.mapstruct:mapstruct-processor", version.ref = "mapstruct" }

# Testing
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
mockito-core = { module = "org.mockito:mockito-core", version.ref = "mockito" }
testcontainers-junit = { module = "org.testcontainers:junit-jupiter", version.ref = "testcontainers" }
testcontainers-postgresql = { module = "org.testcontainers:postgresql", version.ref = "testcontainers" }

[bundles]
spring-boot-web = ["spring-boot-starter-web", "spring-boot-starter-actuator"]
spring-data = ["spring-boot-starter-data-jpa", "postgresql", "flyway-core"]
gcp = ["spring-cloud-gcp-starter", "spring-cloud-gcp-pubsub", "google-cloud-secretmanager"]
testing = ["junit-jupiter", "mockito-core", "spring-boot-starter-test"]
testcontainers = ["testcontainers-junit", "testcontainers-postgresql"]

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }
spring-dependency-management = { id = "io.spring.dependency-management", version = "1.1.7" }
jib = { id = "com.google.cloud.tools.jib", version = "3.4.4" }

Step 2: Configure in Settings File

Update 
settings.gradle.kts
to use the version catalog:
kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

// For multi-module projects
rootProject.name = "supplier-charges"
include("shared-domain")
include("supplier-charges-hub")

Step 3: Use in Build Scripts

In 
build.gradle.kts
, use type-safe dependency references:
kotlin
plugins {
    alias(libs.plugins.spring.boot)
    alias(libs.plugins.spring.dependency.management)
}

dependencies {
    // Single dependencies
    implementation(libs.spring.boot.starter.web)
    implementation(libs.mapstruct)
    annotationProcessor(libs.mapstruct.processor)

    // Bundles (groups of related dependencies)
    implementation(libs.bundles.spring.boot.web)
    implementation(libs.bundles.gcp)
    testImplementation(libs.bundles.testing)
    testImplementation(libs.bundles.testcontainers)
}

Step 4: Manage BOMs for Curated Versions

Use Bill of Materials to control transitive dependencies:
kotlin
// build.gradle.kts
dependencyManagement {
    imports {
        mavenBom("com.google.cloud:spring-cloud-gcp-dependencies:6.1.1")
        mavenBom("org.springframework.cloud:spring-cloud-dependencies:2024.0.1")
    }
}

dependencies {
    // No version needed - comes from BOM
    implementation("com.google.cloud:spring-cloud-gcp-starter")
    implementation("org.springframework.cloud:spring-cloud-config-client")
}

Step 5: Resolve Conflicts with Constraints

Use dependency constraints to force specific versions without declaring the dependency:
kotlin
dependencies {
    // Actual dependencies
    implementation("org.springframework.boot:spring-boot-starter-web")

    // Constraints - enforce versions of transitive dependencies
    constraints {
        implementation("org.bouncycastle:bcprov-jdk15on:1.70")
        implementation("ch.qos.logback:logback-core:1.5.19")
    }
}
To exclude a problematic transitive dependency:
kotlin
dependencies {
    implementation("com.example:library:1.0") {
        exclude(group = "commons-logging", module = "commons-logging")
    }
}

Examples

Example 1: Multi-Module with Shared Catalog

toml
# gradle/libs.versions.toml
[versions]
spring-boot = "3.5.5"

[libraries]
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }
spring-boot-starter-test = { module = "org.springframework.boot:spring-boot-starter-test" }

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }
kotlin
// Root settings.gradle.kts
rootProject.name = "supplier-charges"

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

include("shared-domain")
include("supplier-charges-hub")
include("supplier-charges-worker")
kotlin
// shared-domain/build.gradle.kts
plugins {
    id("java-library")
}

dependencies {
    api(libs.spring.boot.starter.web)
}
kotlin
// supplier-charges-hub/build.gradle.kts
plugins {
    alias(libs.plugins.spring.boot)
}

dependencies {
    implementation(project(":shared-domain"))
    testImplementation(libs.spring.boot.starter.test)
}

Example 2: Resolving Dependency Conflicts

kotlin
// When Spring Boot and external library have conflicting versions
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("com.external:library:1.0")  // Uses old commons-lang3

    // Force the newer version
    constraints {
        implementation("org.apache.commons:commons-lang3:3.18.0")
    }
}

// Or use resolutionStrategy
configurations.all {
    resolutionStrategy {
        force("com.google.guava:guava:32.1.3-jre")
        force("org.apache.commons:commons-compress:1.26.0")
    }
}

Example 3: Security-Focused Constraints

toml
# gradle/libs.versions.toml with security-critical versions
[constraints]
bouncycastle = "1.70"           # Cryptography
logback = "1.5.19"              # Logging
jackson = "2.17.2"              # JSON processing
commons-lang3 = "3.18.0"        # Common utilities
kotlin
// build.gradle.kts
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")

    constraints {
        implementation("org.bouncycastle:bcprov-jdk15on:${libs.versions.bouncycastle.get()}")
        implementation("ch.qos.logback:logback-core:${libs.versions.logback.get()}")
        implementation("com.fasterxml.jackson.core:jackson-databind:${libs.versions.jackson.get()}")
        implementation("org.apache.commons:commons-lang3:${libs.versions.commons.lang3.get()}")
    }
}

Example 4: Using Version Ref in BOM

toml
# gradle/libs.versions.toml
[versions]
spring-cloud-gcp = "6.1.1"

[libraries]
spring-cloud-gcp-bom = { module = "com.google.cloud:spring-cloud-gcp-dependencies", version.ref = "spring-cloud-gcp" }
spring-cloud-gcp-starter = { module = "com.google.cloud:spring-cloud-gcp-starter" }
spring-cloud-gcp-pubsub = { module = "com.google.cloud:spring-cloud-gcp-starter-pubsub" }

[bundles]
gcp = ["spring-cloud-gcp-starter", "spring-cloud-gcp-pubsub"]
kotlin
// build.gradle.kts
dependencyManagement {
    imports {
        mavenBom(libs.spring.cloud.gcp.bom.get().toString())
    }
}

dependencies {
    implementation(libs.bundles.gcp)
}

Requirements

  • Gradle 7.0+ (version catalogs stable since Gradle 7.0)
  • settings.gradle.kts
    file in project root
  • Spring Boot Gradle plugin for Spring Boot projects (optional but recommended)

Commands

bash
# List all dependencies
./gradlew dependencies

# Show dependency tree for specific configuration
./gradlew dependencies --configuration implementation

# Show why a dependency is included
./gradlew dependencyInsight --dependency spring-core

# Refresh dependencies (force re-download)
./gradlew build --refresh-dependencies

# Lock dependency versions for reproducibility
./gradlew dependencies --write-locks

# Verify against lock files
./gradlew dependencies --verify-locks

# Generate HTML dependency report
./gradlew htmlDependencyReport

See Also