Quarkus Modulith brings Spring Modulith 2.1 to Quarkus. You keep one deployable application, split into modules by package, and the build checks that the modules respect each other's boundaries. Modules talk through events with a transactional outbox, and the build documents the result.
The module model is computed from the Jandex index and the class files during the build. Nothing is scanned at runtime, so native executables behave like the JVM. Annotation names, attributes, rule semantics, violation messages and the event_publication table match Spring Modulith, so a migration is mostly an import change. The migration page maps the Spring Modulith 2.1.2 features to their Quarkus counterparts.
- Modules and verification. Each direct sub-package of the base package is a module (or only annotated packages, or a custom strategy).
@ApplicationModule(id,displayName,allowedDependencies,type),@NamedInterface(with propagation), nested modules, shared modules,@Modulith/@Modulithic,@PackageInfo, jMolecules@Module, and the Spring Modulith annotations themselves during a migration. The build fails on cycles between closed modules, access to internals, and dependenciesallowedDependenciesdoes not list.ApplicationModules.of(App.class).verify()also works in a plain JUnit test, with ArchUnit and jMolecules rules when they are on the class path. - Runtime model. An
ApplicationModulesbean read from a compressed resource on first use,ApplicationModuleInitializerbeans run in module dependency order at startup, and/q/modulithwith Spring's actuator JSON (dev and test mode, or on explicit opt-in). - Module events.
@ApplicationModuleListenerruns after the publishing transaction commits, asynchronously, in a new transaction, withcondition,propagation,readOnlyTransactionand composed annotations. CDIAFTER_SUCCESSobservers go through the registry too. - Event publication registry. Every delivery is stored in the publishing transaction (
PUBLISHED,PROCESSING,COMPLETED,FAILED,RESUBMITTED), with republish on restart, scheduled resubmission, staleness monitoring,UPDATE/DELETE/ARCHIVEcompletion modes, and multi-instance safety through compare-and-set claims. Stores: Hibernate ORM, JDBC (H2, HSQLDB, PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, v1 and v2 schemas), MongoDB and Neo4j. - Externalization.
@ExternalizedandEventExternalizationConfiguration, in module-listener or outbox mode, marked done only after the broker acknowledged: Kafka, RabbitMQ and AMQP 1.0 through Quarkus Messaging, JMS, and JobRunr. Routing expressions are compiled at build time, including the common Spring SpEL forms. - Moments.
HourHasPassed,DayHasPassed,WeekHasPassed,MonthHasPassed,QuarterHasPassed,YearHasPassed(plus seconds and minutes) from the scheduler, and aTimeMachinefor tests. - Observability. OpenTelemetry spans around calls into a module and Micrometer counters for module events, with Spring Modulith's names, plus gauges per publication status.
- Documentation. C4 and UML PlantUML diagrams, Mermaid, module canvases and
all-docs.adoc, written by the build or byDocumenterin a plain test, with Javadoc from an annotation processor. The Dev UI shows modules, graph, violations, listeners, initializers and incomplete publications with a resubmit action. - Testing.
@ApplicationModuleTestwith bootstrap modes,Scenario,PublishedEventsand AssertJ assertions, module component slices onQuarkusComponentTest, and change-aware test execution that skips modules whose code did not change. - Module-aware Flyway. One migration folder and history table per module, migrated in dependency order.
| Artifact | Purpose |
|---|---|
quarkus-modulith |
The core extension: module model, build-time verification, listeners, initializers, docs at build, /q/modulith, Dev UI |
quarkus-modulith-dev |
Dev UI backend, added by Quarkus in dev mode only (do not declare it) |
quarkus-modulith-api |
Annotations and the events API, without any Quarkus dependency |
quarkus-modulith-core |
Module model and verification, usable in a plain JUnit test (ApplicationModules.of) |
quarkus-modulith-events |
Registry core: lifecycle, jobs, repository and serializer SPI, externalization core |
quarkus-modulith-events-jpa |
Registry store on Hibernate ORM |
quarkus-modulith-events-jdbc |
Registry store on plain JDBC (Agroal), with schemas per database |
quarkus-modulith-events-mongodb |
Registry store on MongoDB |
quarkus-modulith-events-neo4j |
Registry store on Neo4j |
quarkus-modulith-events-messaging |
Externalization through Quarkus Messaging (Kafka, RabbitMQ, AMQP 1.0) |
quarkus-modulith-events-jms |
Externalization through a Jakarta Messaging JMSContext |
quarkus-modulith-events-jobrunr |
Externalization through JobRunr jobs enqueued in the business transaction |
quarkus-modulith-events-tck |
Contract tests for registry stores, with an in-memory store (test scope) |
quarkus-modulith-moments |
Passage of time events and TimeMachine |
quarkus-modulith-observability |
Spans and metrics |
quarkus-modulith-flyway |
Module-aware Flyway migrations |
quarkus-modulith-documenter |
Documenter for plain tests |
quarkus-modulith-apt |
Annotation processor recording Javadoc for canvases and the Dev UI |
quarkus-modulith-junit |
Module tests, scenarios, published events (test scope) |
quarkus-modulith-junit-changes |
Change-aware test execution (test scope) |
quarkus-modulith-bom |
Version alignment |
The artifacts are published to Maven Central under the group io.quarkiverse.modulith. Java 21 or later is required. Each Quarkus line has its own branch:
| Quarkus | Quarkus Modulith | Branch |
|---|---|---|
| 4.0 | 2.0.x (pre-releases such as 2.0.0.CR1 until Quarkus 4.0 is final) | main |
| 3.40 | 1.0.x | 1.x |
Import the BOM next to the Quarkus BOM. On Quarkus 3.40, use the Quarkus 3.40 BOM with a 1.0.x version of the extension instead:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-bom</artifactId>
<version>4.0.0.CR1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>io.quarkiverse.modulith</groupId>
<artifactId>quarkus-modulith-bom</artifactId>
<version>2.0.0.CR1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>Add the extensions you need, without versions:
<dependencies>
<dependency>
<groupId>io.quarkiverse.modulith</groupId>
<artifactId>quarkus-modulith</artifactId>
</dependency>
<dependency>
<groupId>io.quarkiverse.modulith</groupId>
<artifactId>quarkus-modulith-events-jpa</artifactId>
</dependency>
<dependency>
<groupId>io.quarkiverse.modulith</groupId>
<artifactId>quarkus-modulith-junit</artifactId>
<scope>test</scope>
</dependency>
</dependencies>Mark the base package (optional) and declare a module:
@Modulith(systemName = "Shop", sharedModules = "common")
public class ShopApplication {
}@ApplicationModule(allowedDependencies = { "order::events", "common" })
package com.acme.shop.inventory;
import io.quarkiverse.modulith.ApplicationModule;Publish with a plain CDI Event and listen in another module:
@ApplicationScoped
public class OrderService {
@Inject
Event<OrderPlaced> events;
@Transactional
public void place(Order order) {
// ...
events.fire(new OrderPlaced(order.id()));
}
}public class InventoryListener {
@ApplicationModuleListener
void on(OrderPlaced event) {
// runs after the order transaction committed, in its own transaction
}
}If the inventory module used a class from com.acme.shop.order.internal, for example with new PurchaseOrder(event.orderId()) in an InventoryListener of com.acme.shop.inventory.internal, ./mvnw package would stop with
[ERROR] Failed to execute goal io.quarkus:quarkus-maven-plugin:3.40.1.2:build (default) on project shop: Failed to build quarkus application: io.quarkus.builder.BuildException: Build failure: Build failed due to errors
[ERROR] [error]: Build step io.quarkiverse.modulith.deployment.ModelProcessor#moduleModel threw an exception: io.quarkiverse.modulith.core.Violations: - Module 'inventory' depends on non-exposed type com.acme.shop.order.internal.PurchaseOrder within module 'order'!
[ERROR] Method <com.acme.shop.inventory.internal.InventoryListener.on(com.acme.shop.order.events.OrderPlaced)> calls constructor <com.acme.shop.order.internal.PurchaseOrder.<init>(java.lang.String)> in (InventoryListener.java:12)
Each violation starts with - , followed by one line per reference that causes it.
The full guide is in docs, the public API in the API page, and the migration from Spring Modulith in the migration page. ARCHITECTURE.md explains how the extension works.
./mvnw verify
The build needs Java 21 or later and Docker, because the integration tests start databases and brokers with Dev Services. It fails below 100% line or branch coverage; the merged report is in coverage/target/site/jacoco. The extension builds against Quarkus 4.0.0.CR1. The Quarkus 3.40 line is built from the 1.x branch.
To build and test the native executables on Linux, run
./mvnw verify -Dnative -Dquarkus.native.container-build=true -pl integration-tests/shop,integration-tests/violations -am
On macOS the Linux executable cannot run on the host, so the tests run it in a container image instead:
./mvnw verify -Dnative -Dquarkus.native.container-build=true -Dquarkus.container-image.build=true -Dquarkus.jib.platforms=linux/arm64/v8 -pl integration-tests/shop -am
Releases follow the Quarkiverse release process. main always carries 999-SNAPSHOT. To release, open a pull request that sets current-version (the version to release) and next-version (999-SNAPSHOT) in .github/project.yml. The Quarkiverse Pre Release check validates the versions; merging the pull request runs Quarkiverse Prepare Release, which tags the release and creates the GitHub release, and the tag triggers Quarkiverse Perform Release, which publishes the artifacts to Maven Central. Each line is released from its own branch: Quarkus 4 from main, Quarkus 3.40 from 1.x, through a pull request to that branch.
Apache License 2.0. See LICENSE.
Thanks goes to these wonderful people (emoji key):
Lucas Ângelo O. M. Rocha 💻 🚧 |
This project follows the all-contributors specification. Contributions of any kind welcome!