gradle-standards

• Setting up a new Gradle project
• Adding or updating dependencies
• Configuring multi-module builds
• Troubleshooting dependency conflicts
• Migrating to version catalogs
• Cleaning up unused dependencies
• Optimizing build performance

Sections

• [When to use this skill](#when-to-use-this-skill) (L23-L32)
• [Quick Start](#quick-start) (L60-L88)
• [Key Principles](#key-principles) (L89-L101)
• [Version Alignment](#version-alignment) (L102-L129)
• [References](#references) (L130-L141)
• [Related Rules](#related-rules) (L142-L146)
• [Dependency Resolution Stack](#dependency-resolution-stack) (L147-L186)
• [Related Skills](#related-skills) (L187-L195)

Available Resources

📚 references/ - Detailed documentation

• [cleanup workflow](references/cleanup-workflow.md)
• [multi module](references/multi-module.md)
• [native dependency locking](references/native-dependency-locking.md)
• [optimization](references/optimization.md)
• [scope optimization](references/scope-optimization.md)
• [troubleshooting](references/troubleshooting.md)
• [unused detection](references/unused-detection.md)
• [version catalogs](references/version-catalogs.md)

---

1. Version Centralization (Required)

All versions MUST be centralized in gradle/libs.versions.toml:

```toml

[versions]

spring-boot = "3.5.9"

grpc = "1.78.0"

[libraries]

spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "spring-boot" }

spring-boot-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator", version.ref = "spring-boot" }

```

2. Use in build.gradle

```groovy

dependencies {

// ✅ CORRECT: Use version catalog with explicit dependencies

implementation libs.spring.boot.starter.web

implementation libs.spring.boot.starter.actuator

// ❌ NEVER: Hardcode versions

// implementation "org.springframework.boot:spring-boot-starter-web:3.5.9"

}

```

| Principle | Description |

|-----------|-------------|

| Centralize Versions | All versions in libs.versions.toml, never inline |

| Explicit Dependencies | Declare each dependency explicitly for clarity |

| Use Native Locking | Use Gradle's native dependency locking (Gradle 9+ recommended) |

| Never Downgrade | Don't replace existing versions with older ones |

| Trust BOMs | Spring Boot BOM manages transitive dependencies |

| Platform Over Enforce | Use platform(), never enforcedPlatform() |

| Use resolutionStrategy | Use Gradle's native resolutionStrategy for version control |

| Lock Dependencies | Generate gradle.lockfile for ALL submodules (use build --write-locks) |

Use Gradle's native resolutionStrategy to ensure all modules in a library group use the same version:

```groovy

// build.gradle - Native Gradle version alignment

configurations.configureEach {

resolutionStrategy {

// Force specific versions for security or compatibility

force libs.jackson.core

force libs.jackson.databind

// Align all modules in a group

eachDependency { details ->

if (details.requested.group == 'io.grpc') {

details.useVersion libs.versions.grpc.get()

}

}

}

}

```

This approach is preferred because:

• Subprojects can declare exactly what they need
• Dependencies are explicit and visible in build files
• No external plugins required (built into Gradle)
• First-class support in Gradle 9+

| Reference | Description |

|-----------|-------------|

| [references/version-catalogs.md](references/version-catalogs.md) | Complete version catalog guide |

| [references/multi-module.md](references/multi-module.md) | Multi-module project setup |

| [references/native-dependency-locking.md](references/native-dependency-locking.md) | Gradle native locking (Gradle 9+ recommended) |

| [references/cleanup-workflow.md](references/cleanup-workflow.md) | Dependency cleanup process |

| [references/unused-detection.md](references/unused-detection.md) | Finding unused dependencies |

| [references/optimization.md](references/optimization.md) | Build optimization techniques |

| [references/troubleshooting.md](references/troubleshooting.md) | Common issues and solutions |

• .cursor/rules/java-gradle-best-practices.mdc - Full Gradle configuration reference
• .cursor/rules/java-versions-and-dependencies.mdc - Version management policies

```

┌─────────────────────────────────────────────────────────────────────┐

│ 1. VERSION CATALOG (libs.versions.toml) │

│ Single source of truth for declared versions │

├─────────────────────────────────────────────────────────────────────┤

│ 2. RESOLUTION STRATEGY (build.gradle) │

│ Use Gradle's native resolutionStrategy for: │

│ - force() for security fixes │

│ - eachDependency for group alignment │

│ - dependencySubstitution for module replacement │

├─────────────────────────────────────────────────────────────────────┤

│ 3. LOCK FILE (gradle.lockfile) │

│ Native Gradle locking (Gradle 9+ recommended) │

│ Captures EXACT resolved versions │

│ │

│ ⚠️ CRITICAL: Multi-module projects need lockfiles for ALL modules │

│ Use: ./gradlew build --write-locks -x test │

│ NOT: ./gradlew dependencies --write-locks (root only!) │

└─────────────────────────────────────────────────────────────────────┘

```

Lock File:

• [Native locking](references/native-dependency-locking.md) - Built-in, no plugins, recommended for Gradle 9+

Multi-Module Lockfile Generation:

```bash

# ✅ CORRECT: Generates lockfiles for ALL submodules

./gradlew build --write-locks -x test

# ❌ WRONG: Only generates for ROOT project

./gradlew dependencies --write-locks

# Verify coverage (lockfiles should ≈ build.gradle files)

find . -name "gradle.lockfile" | wc -l

find . -name "build.gradle" | wc -l

```

| Skill | Purpose |

|-------|---------|

| dependency-management | Version catalogs and BOMs |

| dependabot-security | Security vulnerability fixes |

| java-coverage | JaCoCo configuration in Gradle |

| java-testing | Test configuration with Spock |