Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

Extensions and the BOM

Learn what Quarkus extensions are, how runtime and deployment modules differ, how the BOM manages versions, and how to find, add and choose extensions.

In Quarkus, almost every feature is an extension: REST, JSON, Hibernate, security, Kafka, health checks, OpenAPI. Adding a feature means adding one dependency. But an extension is more than a library. It also contains build-time logic that configures the library, removes unused code and makes it work in a native image.

This lesson explains what is inside an extension, how the platform keeps versions consistent, how to find the right extension and how to think about the cost of adding one. The real commands and pom.xml snippets are read-only. The two runnable stand-ins model how an extension registers itself and how a dependency list resolves to features.

What an extension is

Each extension is really two modules:

Module Contains Present when
Runtime (quarkus-rest) The code your application calls and runs: recorders, annotations, configuration classes In your running app
Deployment (quarkus-rest-deployment) Build steps: they scan your code, decide what to generate, register reflection hints Only during the build

You only add the runtime artifact to your pom.xml. Quarkus finds the matching deployment module on its own and runs it while building. That split is why the running application carries no build machinery: the heavy analysis code is not even on the classpath when it runs.

Inside an extension

Library The real tool, such as Hibernate or Jackson.
Build steps Scan, validate, generate bytecode.
Recorders Small runtime code that replays decisions.
Config Properties with documented defaults.

Build steps run once. Recorders run at startup.

1 / 2

The platform BOM

The Quarkus platform is a BOM that fixes the versions of the core, hundreds of extensions and the third-party libraries they wrap. You import it once (as you saw in Creating a Quarkus Project) and then declare extensions without versions:

XML
<dependencies>
  <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-orm-panache</artifactId>
  </dependency>
  <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-postgresql</artifactId>
  </dependency>
  <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-hibernate-validator</artifactId>
  </dependency>
</dependencies>

Upgrading Quarkus is then a one-line change, quarkus.platform.version. There is also quarkus update, a command that updates the version and applies automatic migrations to your code and configuration.

Quarkus releases a new minor version about every month and designates LTS (long-term support) releases that get fixes for longer. Production teams commonly pin an LTS version.

Finding and adding extensions

Terminal
quarkus extension list --installable --search=kafka
quarkus extension add rest-jackson hibernate-validator
quarkus extension remove hibernate-validator

Or with Maven only:

Terminal
./mvnw quarkus:list-extensions
./mvnw quarkus:add-extension -Dextensions="smallrye-health"

The web page code.quarkus.io lists extensions with categories (Web, Data, Messaging, Security, Observability, Cloud, Compatibility) and shows an extension's guide. The official guides on quarkus.io have a page for each extension. Names have patterns:

  • quarkus-rest is the server side of REST. quarkus-rest-jackson adds JSON through Jackson, quarkus-rest-jsonb through JSON-B. quarkus-rest-client calls other services.
  • quarkus-hibernate-orm is JPA. quarkus-hibernate-orm-panache adds the Panache helpers.
  • quarkus-jdbc-* are database drivers (postgresql, mysql, h2, mariadb).
  • quarkus-smallrye-* implement MicroProfile specs (health, OpenAPI, fault tolerance, JWT).
  • quarkus-messaging-* are reactive messaging connectors (Kafka, AMQP, RabbitMQ).

Not every Java library is an extension. Many plain libraries work unchanged on the JVM, for example Apache Commons or Guava. For native image, an extension (or a reflection configuration) matters more, because GraalVM needs to know what code is reachable.

Extension configuration

Each extension owns a namespace of configuration properties under quarkus.. For example:

PROPERTIES
quarkus.http.port=9090
quarkus.datasource.db-kind=postgresql
quarkus.hibernate-orm.database.generation=drop-and-create
quarkus.log.level=INFO

Run ./mvnw quarkus:info to see the platform and extensions in use. The generated reference page in every extension's guide lists all properties with their defaults and whether they are build-time fixed (marked with a lock icon). A build-time property is baked in when you package, so changing it later at runtime has no effect. Config and Profiles is covered later; for now know the difference: "build-time" properties choose which code is generated, while "runtime" properties can be overridden by environment variables when the app starts.

An extension registry stand-in

This stand-in models extension discovery: each "extension" declares a capability it provides and a small startup action. The application only lists extension names, and the engine calls each one in order. It illustrates why adding a dependency is enough to turn a feature on.

Java Stand-in: extensions register capabilities

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Choosing extensions wisely

Each extension adds build time, jar size and, for native images, compile time. A few habits help:

  1. Start small. Add only what you use. Dev UI shows which extensions are active.
  2. Prefer the reactive-capable ones. quarkus-rest (the current REST layer) supports blocking and non-blocking methods, so you do not need an old resteasy-classic extension for new projects.
  3. Check the status. Guides mark extensions as stable, preview or experimental. Avoid experimental ones in production.
  4. Use "extension-less" libraries carefully. They may fail in native mode when they depend on reflection.

Also note the extension compatibility layers: quarkus-spring-di, quarkus-spring-web and quarkus-spring-data-jpa accept a subset of Spring annotations, which helps migrate Spring projects gradually.

Resolving features from dependencies

Our second stand-in turns a list of dependency artifact IDs into the list of enabled features. It also catches a frequent mistake: adding Panache without any database driver.

Java Stand-in: which features does my pom enable?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Quarkus reports a missing driver clearly at build or start time ("No datasource has been configured" or an unsatisfied dependency message). Learn to read the first error line, which usually names the extension you forgot.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which module of an extension is on your running application's classpath?

    The runtime module is what you declare. The deployment module with the build steps is used only while building.
  2. 2. Why do quarkus-* dependencies usually have no version in your pom.xml?

    The platform BOM in dependencyManagement fixes the versions of all extensions and libraries so they work together.
  3. 3. What does a lock icon next to a property in the Quarkus configuration reference mean?

    Build-time properties influence generated code, so they are baked in at packaging time.
  4. 4. Which command lists extensions you can add?

    The CLI can list, search, add and remove extensions. ./mvnw quarkus:list-extensions does the same with Maven.

Summary

  • Features come as extensions: a runtime module you depend on plus a deployment module that runs at build time.
  • The platform BOM manages all versions; upgrade with quarkus update.
  • Add and find extensions through the CLI, Maven goals or code.quarkus.io.
  • Properties live under quarkus.*; some are fixed at build time.
  • Add only what you use, and prefer stable extensions.

Next: Build-Time Architecture