gradle-dependency-management

What this skill does

# Gradle Dependency Management

## Table of Contents

- [Purpose](#purpose)
- [When to Use](#when-to-use)
- [Quick Start](#quick-start)
- [Instructions](#instructions)
- [Examples](#examples)
- [Requirements](#requirements)
- [Commands](#commands)
- [See Also](#see-also)

## 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
configur