A maturity matrix for Quarkus extensions

For most extensions, this is the minimum expectation. When wrapping an existing library, this is usually trivial to achieve; if an extension is providing net-new capability, it might be a bit more work. Quarkus provides tools for unit testing and integration testing extensions.

In some cases, extra work may be needed to ensure any wrapped libraries can tolerate dev mode, since the classloading is different and hot reloading can break some assumptions. Extensions may also wish to add some special handling for dev mode. To add automated tests which validate dev mode, you can add tests which extend the QuarkusDevModeTest.

For many libraries, native mode support is the primary motivation for creating an extension. See the guide on native executable support for more discussion about some of the adaptations that might be needed.

Extensions should support Quarkus’s unified configuration, by integrating with the Quarkus configuration model. The Writing Extensions guide has more guidance on the Quarkus configuration philosophy.

Quarkus extensions should aim to expose components via CDI, so that they can be consumed in a frictionless way by user applications. Having everything injectable as CDI beans also helps testing, especially mocking.

Dev Services are generally relevant for extensions that "connect" to something, such as databases for datasources, a keycloak instance for security, an Apache Kafka instance for messaging, etc.

To provide a Dev Service, use the DevServicesResultBuildItem build item. See the Dev Services how-to for more information.

Every extension gets a tile in the Dev UI. The default tile pulls information from the extension metadata, which is another reason to spend a bit of time getting the metadata right.

Extensions also use Dev UI hooks to present extra information to users. For example, the tile could include a link to an external console, or an internal page which presents simple text metrics. See the Dev UI for extension developers guide.

Some extensions provide extremely sophisticated Dev UIs. For example, they might allow users to interact with the running application, respond to reloads, visualise application metrics, or stream an application-specific log. The Dev UI for extension developers guide also explains these more advanced options.

Quarkus’s build-time philosophy means extensions can tidy up API boilerplate and make programming models more concise and expressive. A good starting point is usually to use Jandex to scan user code for annotations and other markers. Although providing new, joyful, ways to do things is good, it’s important to not break the normal patterns that users may be familiar with.

For some inspiration in this area, have a look at simplified logging, simplified Hibernate ORM with Panache, the @RestQuery annotation, or the way Quarkus allows test containers to be used without any configuration.

Codestarts are templates which can be used to generate applications for users. Extensions can provide their own codestart templates.

Do as much initialization as much as possible statically. This avoid runtime overhead.

Many Java libraries make heavy use of reflection to delay decisions to run-time. Quarkus aims to improve performance by moving logic to build time, reducing unnecessary dynamism. Extensions should aim to replace reflection with build-time code. This is enabled by Jandex, an "offline reflection" library. It may also be necessary to do some bytecode transformation of existing libraries.

For a case study of how to eliminate reflection and what the performance benefits turned out to be, see reflectionless Jackson serialization

Not every library is suitable for using with virtual threads, out of the box. "Why not virtual threads everywhere?" explains why.

To get your library working properly with virtual threads, you should make sure the library is not pinning the carrier thread. Quarkus has test helpers to do these checks in an automated way. For dispatching work, you should use the virtual executor managed by Quarkus. The WebSockets-next extension uses the virtual dispatcher and smart dispatch, and is a good example to follow.

Although Quarkus offers some unique opportunities for extension performance, extension developers shouldn’t forget the basics of performance optimization.

Quarkus’s reactive core is a key contributor to its excellent throughput and scalability. Extensions should consider adopting this model for their own internal operations.

For maximum scalability, go beyond the reactive core and enable fully reactive programming, using Mutiny. Most projects that support a reactive programming model offer two distinct extensions, a -reactive and a plain one. See, for example, ElasticSearch and ElasticSearch Reactive extensions.

Quarkus uses JBoss Logging as its logging engine, and supports several logging APIs. (This is normal Java logging, not OpenTelemetry logging.)

Avoid using errors and warnings for conditions that will not affect normal operation. These outputs can cause false alarms in user monitoring systems.

Extensions may wish to define library-specific endpoints for health criteria which are specific to that extension. To add a new endpoint, extensions should produce a NonApplicationRootPathBuildItem.

You should test that OpenTelemetry output for applications using your extension have properly-defined spans. You may need to do extra work to ensure spans are created with the right tracing ID. For example, extensions which have reactive internals should support duplicated contexts for correct context propagation.

Quarkus is designed to be a Kubernetes-native runtime. Extensions can continue this philosophy by adding library-specific integration points with Kubernetes. Being Kubernetes-native implies being container-native. At a minimum, extensions should always work well in containers, but extensions may also have opportunities to integrate with the lower levels of the container stack.