Configuration reference

Quarkus Modulith

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

Whether to write the module documentation (PlantUML and Mermaid diagrams, module canvases, aggregating document and overview) when the application is packaged.

Environment variable: QUARKUS_MODULITH_DOCS_ENABLED

boolean

true

Whether to write the documentation in dev mode too, on every reload. Off by default to keep reloads fast.

Environment variable: QUARKUS_MODULITH_DOCS_DEV_MODE

boolean

false

The directory the documentation is written to. Relative paths are resolved against the build output directory (target with Maven). Defaults to modulith-docs. It must name a sub-directory of the build output of its own: an absolute path outside the build output, ., a path that leaves the build output with .. or a path inside a directory of the build such as classes or quarkus-app fails the build, because the directory is cleaned.

Environment variable: QUARKUS_MODULITH_DOCS_OUTPUT_DIRECTORY

string

modulith-docs

Whether to delete the content of the output directory before writing, so files of renamed or removed modules do not linger. Spring Modulith’s Documenter cleans by default too.

Environment variable: QUARKUS_MODULITH_DOCS_CLEAN

boolean

true

The diagram style: c4 component diagrams or plain uml ones.

Environment variable: QUARKUS_MODULITH_DOCS_DIAGRAM_STYLE

uml, c4

c4

How far the diagram of a module follows the modules whose beans it uses.

Environment variable: QUARKUS_MODULITH_DOCS_DIAGRAM_DEPENDENCY_DEPTH

none, immediate, all

immediate

The dependency types drawn. All types when not set.

Environment variable: QUARKUS_MODULITH_DOCS_DIAGRAM_DEPENDENCY_TYPES

list of uses-component, entity, event-listener, default

Whether modules without a relationship to another module of the diagram are shown.

Environment variable: QUARKUS_MODULITH_DOCS_DIAGRAM_ELEMENTS_WITHOUT_RELATIONSHIPS

hidden, visible

hidden

The groups beans are listed in.

Environment variable: QUARKUS_MODULITH_DOCS_CANVAS_GROUPINGS

quarkus, spring, none

quarkus

Whether internal beans and types are listed as well.

Environment variable: QUARKUS_MODULITH_DOCS_CANVAS_REVEAL_INTERNALS

boolean

false

Whether rows without content are written.

Environment variable: QUARKUS_MODULITH_DOCS_CANVAS_REVEAL_EMPTY_LINES

boolean

false

The base URL of the application’s Javadoc. When set, types link to their Javadoc page.

Environment variable: QUARKUS_MODULITH_DOCS_CANVAS_API_BASE

string

Whether to serve the module model as JSON. Needs an HTTP extension such as quarkus-vertx-http or quarkus-rest. When not set, the endpoint is served in dev and test mode only: the JSON maps the internals of the application, so a packaged application serves it only with true, and should then protect the path or move it to the management interface.

Environment variable: QUARKUS_MODULITH_ENDPOINT_ENABLED

boolean

The path of the endpoint, relative to the non-application root path (/q), or to the management interface root when the management interface is enabled.

Environment variable: QUARKUS_MODULITH_ENDPOINT_PATH

string

modulith

The module under test, given as a module identifier or as any package inside the module. When set, beans of modules that are not part of the test are excluded from the application.

Environment variable: QUARKUS_MODULITH_TEST_MODULE

string

Which other modules are started together with the module under test.

Environment variable: QUARKUS_MODULITH_TEST_BOOTSTRAP_MODE

standalone, direct-dependencies, all-dependencies

standalone

Additional modules to start, by identifier.

Environment variable: QUARKUS_MODULITH_TEST_EXTRA_MODULES

list of string

Whether a module test build fails on any module rule violation of the application, also when quarkus.modulith.verification.mode is warn. Only used when module is set.

Environment variable: QUARKUS_MODULITH_TEST_VERIFY_AUTOMATICALLY

boolean

true

Read by quarkus-modulith-junit-changes: whether to run all tests, without looking at the changed files.

Environment variable: QUARKUS_MODULITH_TEST_SKIP_OPTIMIZATIONS

boolean

false

Read by quarkus-modulith-junit-changes: what to run when no file changed, execute-all (the default) or skip-all (execute-none).

Environment variable: QUARKUS_MODULITH_TEST_ON_NO_CHANGES

string

Read by quarkus-modulith-junit-changes: how changed files are found, default, uncommitted-changes, reference-commit or the name of a FileModificationDetector class.

Environment variable: QUARKUS_MODULITH_TEST_FILE_MODIFICATION_DETECTOR

string

Read by quarkus-modulith-junit-changes: the commit the reference-commit detector compares with.

Environment variable: QUARKUS_MODULITH_TEST_REFERENCE_COMMIT

string

The base package of the application. Every direct sub-package is an application module. When not set, the package of the type annotated with @Modulith is used, or else the longest package prefix shared by all application classes.

Environment variable: QUARKUS_MODULITH_BASE_PACKAGE

string

How modules are found: direct-sub-packages (every direct sub-package of the base package is a module), explicitly-annotated (only packages annotated with @ApplicationModule or jMolecules' @Module), or the fully qualified name of an ApplicationModuleDetectionStrategy with a public no-argument constructor. When not set, a strategy registered as service is used, else direct-sub-packages.

Environment variable: QUARKUS_MODULITH_DETECTION_STRATEGY

string

The name of the system, overriding @Modulith(systemName).

Environment variable: QUARKUS_MODULITH_SYSTEM_NAME

string

Identifiers of modules every other module may depend on, in addition to @Modulith(sharedModules).

Environment variable: QUARKUS_MODULITH_SHARED_MODULES

list of string

Further root packages whose sub-packages are modules, in addition to @Modulith(additionalPackages).

Environment variable: QUARKUS_MODULITH_ADDITIONAL_PACKAGES

list of string

Whether module identifiers default to the full package name, overriding @Modulith(useFullyQualifiedModuleNames).

Environment variable: QUARKUS_MODULITH_USE_FULLY_QUALIFIED_MODULE_NAMES

boolean

Packages left out of the model, in ArchUnit’s notation: com.acme.legacy for the package itself, com.acme.legacy.. for it and its sub-packages, ..generated.. for any package with that segment.

Environment variable: QUARKUS_MODULITH_IGNORED_PACKAGES

list of string

Whether org.springframework.modulith annotations (@ApplicationModule, @NamedInterface, @Modulith, @Modulithic, @PackageInfo, @ApplicationModuleListener) count like Quarkus Modulith’s own, so a code base can keep them while it migrates. The annotations are read from the class files, Spring is not needed.

Environment variable: QUARKUS_MODULITH_SPRING_ANNOTATIONS_ENABLED

boolean

true

What to do when the module rules are broken: fail the build, only log a warn`ing, or skip the verification (`disabled).

Environment variable: QUARKUS_MODULITH_VERIFICATION_MODE

fail, warn, disabled

fail

Whether test classes are part of the module model. Off by default, like in Spring Modulith, so that tests placed in a module package may use the internals of other modules.

Environment variable: QUARKUS_MODULITH_VERIFICATION_INCLUDE_TEST_CLASSES

boolean

false

Whether beans of other modules may be injected into fields. Spring Modulith reports field injection across modules as violation and asks for constructor injection. Quarkus recommends package-private field injection, so it is allowed by default. Set to false for Spring Modulith’s rule.

Environment variable: QUARKUS_MODULITH_VERIFICATION_ALLOW_FIELD_INJECTION

boolean

true

Fully qualified names of io.quarkiverse.modulith.core.ModulithRule implementations with a public no-argument constructor, run with the module rules.

Environment variable: QUARKUS_MODULITH_VERIFICATION_ADDITIONAL_RULES

list of string

Whether to run the jMolecules DDD and architecture rules of jmolecules-archunit at build time, like Spring Modulith does by default in tests. Needs ArchUnit and jmolecules-archunit on the build class path.

Environment variable: QUARKUS_MODULITH_VERIFICATION_JMOLECULES_RULES

boolean

false

Whether the build writes the model in Spring Modulith’s application-modules.json format to META-INF/quarkus-modulith/application-modules.json in the application. Quarkus Modulith does not read the file itself, so enable it only for tools that expect Spring Modulith’s file.

Environment variable: QUARKUS_MODULITH_EXPORT_ENABLED

boolean

false

Where asynchronous listeners run: the Quarkus worker pool, or virtual-threads, which needs the quarkus-virtual-threads extension.

Environment variable: QUARKUS_MODULITH_LISTENERS_EXECUTOR

worker, virtual-threads

worker

How long the application waits at shutdown for listeners that are still running, like Spring Modulith’s spring.modulith.default-async-termination. Deliveries that did not finish stay incomplete in the event publication registry and are submitted again later.

Environment variable: QUARKUS_MODULITH_LISTENERS_SHUTDOWN_TIMEOUT

Duration 

2S

When a publication is marked completed: in-listener, inside the listener’s transaction, or in-interceptor, in a separate transaction after the listener’s transaction committed.

Environment variable: QUARKUS_MODULITH_LISTENERS_COMPLETION_TIMING

in-listener, in-interceptor

in-listener

Whether the PublishedEvents of a test only contain the events published by the test’s thread and the threads it starts, instead of all events published while the test runs. Turn it on when tests run in parallel.

Environment variable: QUARKUS_MODULITH_TEST_THREAD_BOUND_PUBLISHED_EVENTS

boolean

false

About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.

Event publication registry

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

Whether events are externalized when a transport is present, for example quarkus-modulith-events-messaging or an EventExternalizationTransport bean of the application. Like Spring Modulith’s spring.modulith.events.externalization.enabled.

Environment variable: QUARKUS_MODULITH_EVENTS_EXTERNALIZATION_ENABLED

boolean

true

How events reach the broker: module-listener sends them after the publishing transaction commits, outbox records them in the publishing transaction and sends them from a job, through the event publication registry or through JobRunr when quarkus-modulith-events-jobrunr is present. Like Spring Modulith’s spring.modulith.events.externalization.mode.

Environment variable: QUARKUS_MODULITH_EVENTS_EXTERNALIZATION_MODE

module-listener, outbox

module-listener

What happens to a publication once its listener succeeded: update sets the completion date and keeps the row, delete removes it, archive moves it to the archive.

Environment variable: QUARKUS_MODULITH_EVENTS_COMPLETION_MODE

update, delete, archive

update

When set, only CDI observers notified AFTER_SUCCESS whose method carries this annotation get event publications, like Spring Modulith’s spring.modulith.events.registry-trigger-annotation. By default every such observer does, as every @TransactionalEventListener does in Spring Modulith. @ApplicationModuleListener methods always get publications.

Environment variable: QUARKUS_MODULITH_EVENTS_REGISTRY_TRIGGER_ANNOTATION

string

Whether to submit all incomplete publications again when the application starts. The resubmission runs in the background after startup, in batches. With several instances of the application, prefer republish-interval with republish-older-than, since every instance would resubmit the same publications at its start.

Environment variable: QUARKUS_MODULITH_EVENTS_REPUBLISH_OUTSTANDING_EVENTS_ON_RESTART

boolean

false

How often to submit incomplete publications again. Disabled when not set. Needs quarkus-scheduler.

Environment variable: QUARKUS_MODULITH_EVENTS_REPUBLISH_INTERVAL

Duration 

Only publications older than this are submitted again by the periodic job, so that deliveries still in flight are left alone. Without staleness.processing and staleness.resubmitted, it is also the age after which a resubmission takes over a claimed or processing publication, whose instance probably died.

Environment variable: QUARKUS_MODULITH_EVENTS_REPUBLISH_OLDER_THAN

Duration 

5M

How many publications a resubmission reads from the store at once. Must be positive.

Environment variable: QUARKUS_MODULITH_EVENTS_REPUBLISH_BATCH_SIZE

int

100

How often to delete completed publications. Disabled when not set. Needs quarkus-scheduler.

Environment variable: QUARKUS_MODULITH_EVENTS_DELETE_COMPLETED_INTERVAL

Duration 

Completed publications whose completion is older than this are deleted by the periodic job.

Environment variable: QUARKUS_MODULITH_EVENTS_DELETE_COMPLETED_OLDER_THAN

Duration 

7D

After how long a PUBLISHED publication is stale. Must be positive.

Environment variable: QUARKUS_MODULITH_EVENTS_STALENESS_PUBLISHED

Duration 

After how long a PROCESSING publication is stale. Must be positive. A resubmission takes over a claimed or processing publication older than this. The monitor also marks the outbox publications of event externalization failed, so keep it longer than externalization.outbox.send-timeout plus stale-after, or another instance may send a publication that is still being sent.

Environment variable: QUARKUS_MODULITH_EVENTS_STALENESS_PROCESSING

Duration 

After how long a RESUBMITTED publication is stale. Must be positive.

Environment variable: QUARKUS_MODULITH_EVENTS_STALENESS_RESUBMITTED

Duration 

How often to look for stale publications. Must be positive. Needs quarkus-scheduler.

Environment variable: QUARKUS_MODULITH_EVENTS_STALENESS_CHECK_INTERVAL

Duration 

1M

Publications with at least this many completion attempts are abandoned: they are no longer resubmitted and are listed by AbandonedEventPublications. Never when not set.

Environment variable: QUARKUS_MODULITH_EVENTS_RESUBMISSION_ABANDON_AFTER_ATTEMPTS

int

Whether the default externalization configuration sends events one at a time, so that the broker sees them in the order they were published. Like Spring Modulith’s spring.modulith.events.externalization.serialize-externalization. An application that declares its own EventExternalizationConfiguration decides this itself.

Environment variable: QUARKUS_MODULITH_EVENTS_EXTERNALIZATION_SERIALIZE_EXTERNALIZATION

boolean

false

When externalization is serialized, how long one send may wait for the broker’s acknowledgement. A send that takes longer fails, and the next event is sent, so that a broker that never answers cannot stop externalization.

Environment variable: QUARKUS_MODULITH_EVENTS_EXTERNALIZATION_SERIALIZED_SEND_TIMEOUT

Duration 

30S

How often the job looks for publications to send, in addition to running after every transaction that recorded events. Publications that failed are sent again on the next run.

Environment variable: QUARKUS_MODULITH_EVENTS_EXTERNALIZATION_OUTBOX_INTERVAL

Duration 

5S

How long to wait for the broker to acknowledge a message before the publication counts as failed and the run stops, so that later events do not overtake it.

Environment variable: QUARKUS_MODULITH_EVENTS_EXTERNALIZATION_OUTBOX_SEND_TIMEOUT

Duration 

30S

How long, on top of send-timeout, a publication may stay claimed or processing before another instance takes it over, because the instance that claimed it stopped.

Environment variable: QUARKUS_MODULITH_EVENTS_EXTERNALIZATION_OUTBOX_STALE_AFTER

Duration 

1M

How many publications a run reads at once. Must be at least 1.

Environment variable: QUARKUS_MODULITH_EVENTS_EXTERNALIZATION_OUTBOX_BATCH_SIZE

int

100

About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.