name: gradle-standards description: > Gradle build configuration standards for Java projects. Covers version catalogs, dependency bundles, multi-module setup, BOM management, and common troubleshooting. Use when configuring Gradle builds or reviewing dependency management. compatibility: Java projects using Gradle 8.x or 9.x metadata: version: "2.0.0" technology: java category: build tags: - gradle - java - dependencies - build

Gradle Standards

Standards for Gradle configuration in Java projects, including version catalogs, dependency bundles, and multi-module setup.

When to use this skill

• 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
• When asked for "gradle dependencies cleanup"

Skill Contents

Sections

• When to use this skill (L23-L33)
• Quick Start (L61-L89)
• Key Principles (L90-L102)
• Version Alignment (L103-L130)
• References (L131-L142)
• Related Rules (L143-L147)
• Dependency Resolution Stack (L148-L187)
• Related Skills (L188-L195)

Available Resources

📚 references/ - Detailed documentation

• cleanup workflow
• multi module
• native dependency locking
• optimization
• scope optimization
• troubleshooting
• unused detection
• version catalogs

Quick Start

1. Version Centralization (Required)

All versions MUST be centralized in gradle/libs.versions.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

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"
}

Key Principles

Version Alignment

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

// 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+

References

Related Rules

• java-gradle-best-practices - Full Gradle configuration reference
• java-versions-and-dependencies - Version management policies

Dependency Resolution Stack

┌─────────────────────────────────────────────────────────────────────┐
│  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 - Built-in, no plugins, recommended for Gradle 9+

Multi-Module Lockfile Generation:

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

Related Skills