Packaging and JVM Modes

Because fast-jar is the default, its directory shape is worth naming explicitly. ./mvnw package writes it to target/quarkus-app/:

Splitting the layout this way is what makes fast-jar fast to start: the JVM can memory-map an already-indexed, already-separated set of directories instead of opening and scanning a single large archive, and a container image can cache the rarely-changing lib/ layer separately from the frequently-changing app/ layer.

The properties below are the ones most builds actually touch; quarkus.package.jar.* has several more narrowly-scoped options (manifest sections, optional-dependency filtering) covered in full in the Maven Tooling guide linked in References.

src/main/resources/application.properties:

Building the default fast-jar and overriding the type for a one-off uber-jar build both work from the same project, with no other configuration change:

The first command leaves target/quarkus-app/quarkus-run.jar (plus its lib/, app/, quarkus/ siblings) as the runnable artifact, alongside the plain target/inventory-service-1.0.0-SNAPSHOT.jar that Maven’s own jar plugin always produces first and that fast-jar’s build step repackages from. The second command instead leaves a single target/inventory-service-runner.jar containing every dependency’s unpacked classes — nothing under target/quarkus-app/ is produced for that build.

Starting with JDK 24, Project Leyden’s AOT cache lets a JVM process record the classes it loaded and the code the JIT compiled during a representative run, then load that recorded cache on every later start instead of repeating class loading, verification and (re-)JIT-warmup from scratch — narrowing, on the JVM, part of the startup-time gap that has historically favored native image. Quarkus wires this up through the aot-jar package type described above: enabling quarkus.package.jar.aot.enabled=true (via -D on the Maven build, or in application.properties) produces a quarkus-app/ tree structured so the JDK’s own AOT-cache tooling can consume it, and quarkus.package.jar.aot.type selects the cache format (auto, aot, app-cds, or scc, with app-cds as the pre-JDK-24 fallback using the older Application Class-Data Sharing mechanism). The cache itself is trained — built from an actual run of the application, ideally exercising its real request paths — which quarkus.package.jar.aot.phase lets you trigger either during the build or during the project’s own integration tests, so the shipped cache reflects genuine startup and warm-up behavior rather than an empty run. The resulting application still starts with java -jar quarkus-run.jar, but pointed at the cache with an added flag, e.g. -XX:AOTCache=app.aot. Because the cache is tied to the exact JDK build that produced it, it must be regenerated whenever the runtime JDK changes.

Fast-jar’s lib/ directory does not automatically contain only the classes the application actually reaches — by default it contains every class in every declared dependency’s JAR, whether augmentation’s closed-world analysis ever found a path to it or not. quarkus.package.jar.tree-shake.mode turns on tree-shaking: dropping classes from bundled dependency JARs that augmentation determined are unreachable from the application’s own closed-world graph, shrinking both the artifact and the amount the JVM has to index at startup. quarkus.package.jar.tree-shake.excluded-artifacts exempts specific dependency coordinates from shaking — for a library that loads a class reflectively in a way augmentation’s analysis cannot see, tree-shaking it away would silently break that reflective lookup at runtime, so exclude it explicitly rather than disabling tree-shaking project-wide.

A standard JVM deployment bundles the application against a full JRE — every module the JDK ships, whether the application uses it or not. The JDK’s own jlink tool builds a custom runtime image instead: a purpose-built mini-JRE containing only the JDK modules (plus, via Quarkus’s quarkus-jlink extension, the application’s own modules) the application actually needs, alongside a generated launcher script. The result is smaller to store and ship, faster to start because there is less runtime surface to initialize, and more self-contained than depending on whatever JRE image a target host or base container happens to provide. quarkus.jlink.enabled turns image generation on (Maven/Gradle build this image into quarkus.jlink.output-directory, target/jlink-output by default); quarkus.jlink.image-path and quarkus.jlink.launcher-name control where the image and its launcher land, and quarkus.jlink.min-heap-size / quarkus.jlink.max-heap-size bake default heap flags into that launcher. As of this writing the extension needs Java 25 or later and is marked experimental in the upstream guide — worth trying for a leaner JVM-mode container base image, but not yet something to depend on as a stable, unchanging build step.

Adding io.quarkus:quarkus-cyclonedx as a project dependency makes every subsequent ./mvnw package emit a CycloneDX-format Software Bill of Materials for the packaged application automatically — no extra goal invocation is required, and no opt-in flag needs setting once the dependency is present. The distribution SBOM lands next to the built artifact as <executable-name>-cyclonedx.json (the format is configurable via quarkus.cyclonedx.format, e.g. xml); a separate quarkus:dependency-sbom Maven goal can additionally record the dependency graph before packaging, written as target/<artifactId>-<version>-dependency-cyclonedx.json. Either SBOM is what a vulnerability scanner or a supply-chain policy consumes — it lists every artifact, with its coordinates and (where known) license, that ended up in the shipped output.

Packaging and SBOM generation produce the artifacts; getting them from target/ to a GitHub Release, a container registry, and a changelog entry is a separate concern that Quarkus itself has no opinion on. JReleaser is a general-purpose Java release-automation tool that fits well here: pointed at the JARs (or container images) ./mvnw package already produced, it can sign them, publish to Maven Central or a registry, generate release notes, and cut a GitHub/GitLab release, all driven from one declarative configuration file kept alongside the project rather than a hand-rolled release script.

The package types and techniques above, plus native image (covered in Build-Time Augmentation and the Closed World), sit at genuinely different points on the same trade-off curve:

No single row is a universal answer: fast-jar remains the safest default for anything still stabilizing its dependency set, native image is worth its build-time and dependency-compatibility cost for latency- or density-sensitive deployments (serverless, high pod-count Kubernetes), and a JLink runtime is a middle ground worth revisiting as it matures, for JVM deployments that specifically want a smaller, more self-contained image without native image’s closed-world constraints.