gradle-standards

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

Skill Contents

Sections

• When to use this skill (L23-L32)
• Quick Start (L60-L88)
• Key Principles (L89-L101)
• Version Alignment (L102-L128)
• References (L129-L140)
• Related Rules (L141-L145)
• Dependency Resolution Stack (L146-L184)
• Related Skills (L185-L192)

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 Nebula align rules to ensure all modules in a library group use the same version. This is preferred over bundles because:

• Subprojects can declare exactly what they need
• Dependencies are explicit and visible in build files
• Version consistency is enforced at resolution time

// gradle/resolution-rules.json
{
  "align": [
    {
      "name": "jackson-alignment",
      "group": "com\\.fasterxml\\.jackson\\.core",
      "reason": "Jackson modules must use same version"
    },
    {
      "name": "grpc-alignment",
      "group": "io\\.grpc",
      "reason": "gRPC modules must align for binary compatibility"
    }
  ]
}

See Nebula resolution rules documentation for complete align rule reference.

References

Related Rules

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

Dependency Resolution Stack

┌─────────────────────────────────────────────────────────────────────┐
│  1. VERSION CATALOG (libs.versions.toml)                            │
│     Single source of truth for declared versions                    │
├─────────────────────────────────────────────────────────────────────┤
│  2. RESOLUTION RULES (optional: resolution-rules.json)              │
│     Policies: substitute, align, deny, exclude                      │
│     Use substitute for security fixes, align for module groups      │
├─────────────────────────────────────────────────────────────────────┤
│  3. LOCK FILE (captures EXACT resolved versions)                    │
│     Option A: gradle.lockfile (native - Gradle 9+ recommended)      │
│     Option B: dependencies.lock (Nebula plugin)                     │
│                                                                     │
│  ⚠️  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 Options:

• Native locking - Built-in, no plugins, recommended for Gradle 9+
• Nebula resolution rules - Declarative rules for alignment, substitution, and replacement

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