Monorepo with Java: Code Organization for Beginners

Introduction: What is a Monorepo and Why Does a Java Developer Need It?

Imagine you are writing a large Java application: a web service, a library for working with databases, and a separate module for logging. Traditionally, each component is stored in its own Git repository. But there is another approach — monorepo. This is a strategy where all the code of a project (or even several related projects) is stored in a single repository.

For beginner Java developers, a monorepo may seem unusual, but it offers important advantages:

• Single version of dependencies — all modules use the same library versions, eliminating conflicts.
• Simplified refactoring — changing an API in one module is immediately visible in all dependent modules.
• Shared configuration — one configuration file for linter, formatting, and CI/CD.
• Easy start — no need to set up multiple repositories for a small project.

In this article, we will explore how to organize a monorepo in Java using popular build tools: Maven and Gradle. You will learn how to structure folders, configure multi-module builds, and avoid common mistakes.

Main Part

1. Monorepo Structure: From Simple to Complex

A proper folder structure is the foundation of a successful monorepo. Here is a recommended template for a Java project:

my-monorepo/├── build.gradle           # Root build file (for Gradle)├── settings.gradle        # List of modules├── pom.xml                # Root POM (for Maven)├── README.md├── .gitignore├── libs/                  # Shared libraries│   ├── common-utils/│   └── logging-framework/├── services/              # Microservices or applications│   ├── user-service/│   └── payment-service/└── tools/                 # Utilities and scripts    └── code-generator/

Each module is an independent Java project with its own pom.xml or build.gradle. Root configuration files manage dependencies and versions. Let's look at both options in detail.

2. Monorepo with Maven: Multi-Module Project

Maven supports multi-module projects out of the box. Create a root pom.xml specifying the modules:

<project>    <modelVersion>4.0.0</modelVersion>    <groupId>com.example</groupId>    <artifactId>my-monorepo</artifactId>    <packaging>pom</packaging>    <version>1.0.0</version>        <modules>        <module>libs/common-utils</module>        <module>services/user-service</module>        <module>services/payment-service</module>    </modules>

    <dependencyManagement>        <dependencies>            <dependency>                <groupId>org.springframework.boot</groupId>                <artifactId>spring-boot-dependencies</artifactId>                <version>3.2.0</version>                <type>pom</type>                <scope>import</scope>            </dependency>        </dependencies>    </dependencyManagement></project>

In the common-utils module (folder libs/common-utils), create its own pom.xml that references the parent project:

<project>    <parent>        <groupId>com.example</groupId>        <artifactId>my-monorepo</artifactId>        <version>1.0.0</version>    </parent>    <artifactId>common-utils</artifactId>        <dependencies>        <dependency>