Configuring Gradle for Multi-Module Projects

A multi-module Gradle project uses settings.gradle to define the project structure and convention plugins to share configuration without the brittle subprojects {} pattern.

Project structure and discovery

• settings.gradle includes each subproject with include(':api', ':service', ':domain') — Gradle reads this file first and builds the project tree before any build logic runs
• Subprojects reference each other with dependencies { implementation project(':domain') } — Gradle builds a dependency graph from these references and compiles in the correct order automatically
• Targeted execution: ./gradlew :service:test rebuilds only what that module needs — the domain module compiles if it is a dependency, unrelated modules are skipped

Convention plugins over `subprojects {}`

• subprojects {} in the root build applies settings to every module blindly — a module that needs different behavior requires special-casing with if (project.name == ...), which becomes unmaintainable
• Convention plugins in buildSrc/ are Kotlin or Groovy files that each module explicitly applies: apply plugin: 'com.example.java-conventions' — the module opts in to shared toolchain, test framework, and dependency management configuration
• Different module types apply different convention plugins — an API module applies java-library-conventions, a Spring Boot application applies spring-boot-conventions; the conventions encode the team's standards once and modules consume them

When to start with convention plugins

• Start with convention plugins from day one, not subprojects {} — migrating later requires touching every module's build file and is the most common source of inconsistency in multi-module Gradle projects
• Use dependencyResolutionManagement in settings.gradle for the version catalog — centralizing coordinates there makes them available to all modules without each module importing the catalog separately