Maven Expert

maven-expert

> Keyword: maven | Platforms: gemini,claude,codex

Apache Maven Build Tool Expert Skill - The foundation of Java dependency management and project structure.

Core Mandates

• BOM Management: Always prefer BOM (Bill of Materials) to manage versions (e.g., quarkus-bom, jackson-bom) to avoid dependency hell.
• Dependency Scope: Rigorously use compile, provided, runtime, and test scopes for cleaner artifacts.
• Transitive Discipline: Use mvn dependency:tree to identify and exclude conflicting transitive dependencies.
• Reproducible Builds: Lock down plugin versions in ``.

pom.xml Examples

Quarkus Project with BOM

    4.0.0

    com.example
    my-service
    1.0.0-SNAPSHOT

    
        3.20.1
        21
        UTF-8
        3.5.2
    

    
        
            
            
                io.quarkus.platform
                quarkus-bom
                ${quarkus.platform.version}
                pom
                import
            
        
    

    
        
        
            io.quarkus
            quarkus-rest
        
        
            io.quarkus
            quarkus-arc
        
        
            io.quarkus
            quarkus-hibernate-orm-panache
        

        
        
            io.quarkus
            quarkus-junit5
            test
        
        
            io.rest-assured
            rest-assured
            test
        
    

    
        
            
                io.quarkus.platform
                quarkus-maven-plugin
                ${quarkus.platform.version}
                true
                
                    
                        
                            build
                            generate-code
                        
                    
                
            
        
    

Multi-Module Parent POM

    4.0.0
    com.example
    parent
    1.0.0-SNAPSHOT
    pom

    
        common
        service-user
        service-order
    

    
        3.20.1
        21
    

    
        
            
                io.quarkus.platform
                quarkus-bom
                ${quarkus.platform.version}
                pom
                import
            
            
            
                com.example
                common
                ${project.version}
            
        
    

    
    
        
            
                
                    maven-compiler-plugin
                    3.13.0
                
                
                    maven-surefire-plugin
                    3.5.2
                
            
        
    

Dependency Scope Decision Tree

Is this library needed at compile time AND runtime?
  YES → compile (default, usually omit )
Is it provided by the runtime container (Quarkus, app server)?
  YES → provided (e.g., jakarta.servlet-api, quarkus internals)
Is it only needed at runtime, not compiled against?
  YES → runtime (e.g., JDBC drivers, SLF4J implementations)
Is it only for tests?
  YES → test
Is it needed only at build time for annotation processing?
  YES → provided + annotation processor config in compiler plugin

Version Conflict Resolution Workflow

Step 1: Identify the conflict

# Show full dependency tree
mvn dependency:tree -Dincludes=com.fasterxml.jackson

# Output shows conflicting versions:
# [INFO] +- io.quarkus:quarkus-rest-jackson:jar:3.20.1:compile
# [INFO] |  \- com.fasterxml.jackson.core:jackson-databind:jar:2.18.2:compile
# [INFO] +- some-other-lib:jar:1.0:compile
# [INFO] |  \- com.fasterxml.jackson.core:jackson-databind:jar:2.14.0:compile  ← CONFLICT!

Step 2: Analyze with verbose output

# Show why a specific version was chosen
mvn dependency:tree -Dverbose -Dincludes=jackson-databind

# Find unused or undeclared deps
mvn dependency:analyze

Step 3: Resolve

    some-other-lib
    some-other-lib
    1.0
    
        
            com.fasterxml.jackson.core
            jackson-databind
        
    

    
        
            com.fasterxml.jackson
            jackson-bom
            2.18.2
            pom
            import
        
    

    
        com.fasterxml.jackson.core
        jackson-databind
        2.18.2
    

Resolution Priority

| Priority | Strategy | When to use | |----------|----------|-------------| | 1st | BOM import | When a BOM exists for the library (jackson-bom, netty-bom) | | 2nd | `` | When one specific lib brings a bad transitive | | 3rd | Direct declaration | Last resort - harder to maintain |

Common Errors & Fixes

"package X does not exist" after mvn compile

# Cause: Missing dependency or wrong scope
mvn dependency:tree | grep "the-missing-package"

# Fix: Add missing dependency or change scope from test/provided to compile

"Non-resolvable parent POM"

    com.example
    parent
    1.0.0-SNAPSHOT
    ../pom.xml  

Tests pass locally but fail on CI

    maven-surefire-plugin
    
        false  
        
        1C  
    

"Could not find artifact" in private registry

    
        
            private-repo
            ${env.MAVEN_USER}
            ${env.MAVEN_TOKEN}
        
    

    
        private-repo  
        https://nexus.example.com/repository/maven-releases/
    

Slow builds

# Parallel build (1 thread per CPU core)
mvn install -T 1C

# Skip tests when iterating
mvn install -DskipTests

# Build only specific module + its dependencies
mvn install -pl service-user -am

# Offline mode (skip remote checks)
mvn install -o

Maven-to-Bazel Migration

• Dependency Extraction: Identify external dependencies for maven_install in rules_jvm_external.
• Pom-to-Build: Mapping Maven : to Bazel @maven//:group_artifact targets.
• Resource Management: Translating Maven's src/main/resources convention to Bazel resources attributes.

Migration Mapping Table

| Maven Concept | Bazel Equivalent | |---------------|------------------| | ` | deps = [...] | | | deps = [...] (with neverlink = True) | | | runtime_deps = [...] | | | test target deps | | subproject | //subproject:target | | mvn install | bazel build //... | | mvn test | bazel test //...` |

Optimization & Plugins

• Multi-module Projects: Efficiently managing parent-child relationships and ``.
• Essential Plugins: Config and optimization for maven-compiler-plugin, maven-surefire-plugin, and maven-shade-plugin.
• Profiles: Using -P profiles for environment-specific configurations (dev, staging, prod).

Expert Tips

• Avoid LATEST or RELEASE; it breaks build reproducibility.
• Use mvn dependency:analyze to find unused declared dependencies.
• Prefer provided scope for libraries that should be part of the runtime container (like Quarkus-core during augmentation).
• Use mvn versions:display-dependency-updates to check for outdated dependencies.
• Always use `` in parent POM, never hardcode versions in child modules.

🌐 Maven Knowledge Sources

> Directive: Use web_fetch to analyze complex POM structures, dependency conflict resolution strategies, or Maven-to-Bazel migration patterns.

• Maven Dependency Mechanism: Introduction to Dependency Mechanism - Nearest-first, scope, and mediation.
• BOM Import Guide: Introduction to the Bill of Materials - Managing versions centrally.
• Maven-to-Bazel Migration: Migrating from Maven to Bazel - Strategy and tools.
• Quarkus Maven Tooling: Quarkus Maven Guide - Extension management and dev mode.

References

• Apache Maven Official Documentation
• rulesjvm_external (Bazel Maven support)
• Quarkus Official Guides

Skill Interoperability

The maven-expert 📦 skill acts as a source for dependency management and project orchestration, supporting:

• rules-quarkus 🔧: Facilitates the migration of Maven-based projects to Bazel.

Source & license

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

• Author: kinhluan
• Source: kinhluan/rules-quarkus-skills
• License: MIT

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