Maven Gradle Guide

Maven and Gradle Guide

Build tool configuration patterns for Java and Kotlin projects.

When to Use

• User is setting up a new Maven or Gradle project
• User needs to manage dependencies or resolve conflicts
• User is creating a multi-module project
• User asks about BOMs, plugins, or build lifecycle
• User is migrating between Maven and Gradle

Core Patterns

Maven pom.xml Structure

A well-organized POM with property management, dependency management, and plugin configuration.

    4.0.0

    
        org.springframework.boot
        spring-boot-starter-parent
        3.2.0
    

    com.example
    my-service
    1.0.0-SNAPSHOT
    jar

    
        21
        1.19.3
    

    
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
        
    

Gradle Kotlin DSL (build.gradle.kts)

The equivalent Gradle configuration using the Kotlin DSL for type-safe build scripts.

plugins {
    java
    id("org.springframework.boot") version "3.2.0"
    id("io.spring.dependency-management") version "1.1.4"
}

group = "com.example"
version = "1.0.0-SNAPSHOT"

java {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")

    runtimeOnly("org.postgresql:postgresql")

    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("org.testcontainers:postgresql:1.19.3")
}

tasks.test {
    useJUnitPlatform()
}

Multi-Module Project (Maven)

Parent POM manages shared configuration; child modules inherit.

    com.example
    my-platform
    1.0.0-SNAPSHOT
    pom
    
        common
        api
        service
    
    
        
            
                com.example
                common
                ${project.version}
            
        
    

    
        com.example
        my-platform
        1.0.0-SNAPSHOT
    
    service
    
        
            com.example
            common
        
    

Multi-Module Project (Gradle)

// settings.gradle.kts
rootProject.name = "my-platform"
include("common", "api", "service")

// build.gradle.kts (root)
subprojects {
    apply(plugin = "java")
    group = "com.example"
    version = "1.0.0-SNAPSHOT"
    repositories { mavenCentral() }
    java { sourceCompatibility = JavaVersion.VERSION_21 }
    tasks.test { useJUnitPlatform() }
}

// service/build.gradle.kts
dependencies {
    implementation(project(":common"))
    implementation("org.springframework.boot:spring-boot-starter-web")
}

BOM (Bill of Materials)

Use BOMs to align versions across a family of libraries. Prevents version conflicts.

    
        
            org.testcontainers
            testcontainers-bom
            1.19.3
            pom
            import
        
    

    
        org.testcontainers
        postgresql
        test
    

// Gradle: import BOM via platform()
dependencies {
    implementation(platform("org.testcontainers:testcontainers-bom:1.19.3"))
    testImplementation("org.testcontainers:postgresql") // no version needed
}

Anti-Patterns

• Specifying versions in child modules -- Manage all versions in the parent POM's `` or via BOMs. Child modules should omit version tags.
• Using the Groovy DSL for new Gradle projects -- The Kotlin DSL (build.gradle.kts) provides type safety, auto-completion, and compile-time checks. Prefer it for new projects.
• Fat JARs without Spring Boot plugin -- Using the maven-shade-plugin when Spring Boot's plugin handles fat JAR packaging correctly. Use the right tool.
• Dependency version conflicts -- Not using BOMs and having transitive dependency conflicts. Run mvn dependency:tree or gradle dependencies to diagnose.
• Putting test dependencies in compile scope -- Always use test in Maven or testImplementation in Gradle for test-only libraries.

Quick Reference

Maven lifecycle:
  mvn clean compile       -- Compile sources
  mvn test                -- Run tests
  mvn package             -- Build JAR/WAR
  mvn install             -- Install to local repo
  mvn dependency:tree     -- Show dependency tree

Gradle tasks:
  gradle build            -- Compile + test + package
  gradle test             -- Run tests
  gradle dependencies     -- Show dependency tree
  gradle bootRun          -- Run Spring Boot app

Dependency scopes:
  Maven           Gradle
  compile     ->  implementation
  provided    ->  compileOnly
  runtime     ->  runtimeOnly
  test        ->  testImplementation

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VersoXBT
• Source: VersoXBT/claude-initial-setup
• License: MIT
• Homepage: https://github.com/VersoXBT/claude-initial-setup#installation

Install and usage instructions live in the source repository linked above.