Quarkus Application Development
Scope: application code inside an existing Quarkus project. Project creation is create-quarkus-project; Dev Services and tests are quarkus-dev-services-and-testing; native and container images are quarkus-native-and-container; core JPA mapping and query design can use the optional java-hibernate-jpa skill if installed (otherwise see the Hibernate ORM guide, https://quarkus.io/guides/hibernate-orm, and the Jakarta Persistence docs).
Agent rules
- Detect first: read
pom.xml/build.gradle for quarkus.platform.version, the Java release, and the extensions already present. Keep the version; use what the project already uses (for example quarkus-resteasy* stays if present).
- Add extensions with
quarkus extension add <name> or ./mvnw quarkus:add-extension -Dextensions=<name>; never guess artifact ids or versions by hand (the platform BOM manages them). List candidates with quarkus extension list --installable --search=<text>.
- Ask the user before adding Kafka, OIDC/Keycloak or any new infrastructure dependency (they start containers in dev/test and change deployment needs).
- Never use the Spring compatibility extensions (
quarkus-spring-*) unless the project already does.
- Verify with dev mode (
./mvnw quarkus:dev, then /q/dev-ui) and ./mvnw verify; write a @QuarkusTest per feature. Do not claim something works without running it.
- Use
jakarta.* imports, records for DTOs, thin resources delegating to services.
- Never hard-code secrets or add credentials to
application.properties; see references/config-cdi.md.
Quick decisions
| Need |
Use |
Details |
| JSON REST API |
quarkus-rest-jackson, quarkus-hibernate-validator, quarkus-smallrye-openapi |
references/rest.md |
| Typed config |
@ConfigMapping; @ConfigProperty for single values |
references/config-cdi.md |
| Beans |
@ApplicationScoped (default), @Singleton only for plain stateless holders |
references/config-cdi.md |
| Database |
quarkus-hibernate-orm-panache + JDBC driver, repository pattern |
references/persistence.md |
| Async / blocking |
Imperative by default; @RunOnVirtualThread or Uni when needed |
references/reactive-messaging.md |
| Messaging |
quarkus-messaging-kafka (SmallRye Reactive Messaging) |
references/reactive-messaging.md |
| AuthN/AuthZ |
quarkus-oidc, @RolesAllowed |
references/security-oidc.md |
| Ops |
quarkus-smallrye-health, quarkus-micrometer-registry-prometheus, quarkus-opentelemetry, quarkus-smallrye-fault-tolerance |
references/observability-resilience.md |
| Outbound HTTP, scheduling, caching |
quarkus-rest-client-jackson, quarkus-scheduler, quarkus-cache |
references/observability-resilience.md |
Pitfalls that cost time
- Quarkus resolves CDI at build time: an unused bean may be removed. Beans only looked up programmatically need
@Unremovable.
- Do not read or write public fields of a normal-scoped bean (
@ApplicationScoped) from another bean or test: you hit the client proxy, not the instance (verified: a counter field read through the proxy returned 0). Use methods.
- Do not block on the event loop (
@NonBlocking methods, Uni/Multi return types running on I/O threads). Remove any existing @NonBlocking from the method (combining it with @Blocking or @RunOnVirtualThread fails the build), then add @Blocking or @RunOnVirtualThread (see references/reactive-messaging.md).
- Changes to build-time properties need a rebuild; run-time properties can be overridden by env vars (
QUARKUS_DATASOURCE_JDBC_URL).
- Do not configure URLs for databases/brokers/Keycloak in
%dev/%test: that disables Dev Services.
drop-and-create schema management is for dev/test only; use Flyway or Liquibase for production.
Verified on Quarkus 3.40.1 and 3.27.6 (Java 21 target, Maven) with a scaffolded app and mvn verify (15 tests: REST+validation+mapper, OpenAPI, config mapping, Panache on PostgreSQL Dev Services, Kafka Dev Service round trip, Keycloak Dev Service tokens, health, metrics, fault tolerance, cache, scheduler). Re-check names against the project's version.
1---2name: quarkus-application-development3description: 'Write Quarkus application code: REST with Quarkus REST, validation, exception mappers, OpenAPI, configuration, CDI (ArC), Hibernate ORM with Panache, Mutiny and virtual threads, Reactive Messaging with Kafka, OIDC security, health, metrics, OpenTelemetry, fault tolerance, REST Client, scheduler and cache. Use when implementing or changing features in an existing Quarkus project.'4metadata:5 source: https://skillmd.com/skills/github/quarkus-application-development6---78# Quarkus Application Development910Scope: application code inside an existing Quarkus project. Project creation is `create-quarkus-project`; Dev Services and tests are `quarkus-dev-services-and-testing`; native and container images are `quarkus-native-and-container`; core JPA mapping and query design can use the optional `java-hibernate-jpa` skill if installed (otherwise see the Hibernate ORM guide, <https://quarkus.io/guides/hibernate-orm>, and the Jakarta Persistence docs).1112## Agent rules13141. Detect first: read `pom.xml`/`build.gradle` for `quarkus.platform.version`, the Java release, and the extensions already present. Keep the version; use what the project already uses (for example `quarkus-resteasy*` stays if present).152. Add extensions with `quarkus extension add <name>` or `./mvnw quarkus:add-extension -Dextensions=<name>`; never guess artifact ids or versions by hand (the platform BOM manages them). List candidates with `quarkus extension list --installable --search=<text>`.163. Ask the user before adding Kafka, OIDC/Keycloak or any new infrastructure dependency (they start containers in dev/test and change deployment needs).174. Never use the Spring compatibility extensions (`quarkus-spring-*`) unless the project already does.185. Verify with dev mode (`./mvnw quarkus:dev`, then `/q/dev-ui`) and `./mvnw verify`; write a `@QuarkusTest` per feature. Do not claim something works without running it.196. Use `jakarta.*` imports, records for DTOs, thin resources delegating to services.207. Never hard-code secrets or add credentials to `application.properties`; see `references/config-cdi.md`.2122## Quick decisions2324| Need | Use | Details |25|---|---|---|26| JSON REST API | `quarkus-rest-jackson`, `quarkus-hibernate-validator`, `quarkus-smallrye-openapi` | `references/rest.md` |27| Typed config | `@ConfigMapping`; `@ConfigProperty` for single values | `references/config-cdi.md` |28| Beans | `@ApplicationScoped` (default), `@Singleton` only for plain stateless holders | `references/config-cdi.md` |29| Database | `quarkus-hibernate-orm-panache` + JDBC driver, repository pattern | `references/persistence.md` |30| Async / blocking | Imperative by default; `@RunOnVirtualThread` or `Uni` when needed | `references/reactive-messaging.md` |31| Messaging | `quarkus-messaging-kafka` (SmallRye Reactive Messaging) | `references/reactive-messaging.md` |32| AuthN/AuthZ | `quarkus-oidc`, `@RolesAllowed` | `references/security-oidc.md` |33| Ops | `quarkus-smallrye-health`, `quarkus-micrometer-registry-prometheus`, `quarkus-opentelemetry`, `quarkus-smallrye-fault-tolerance` | `references/observability-resilience.md` |34| Outbound HTTP, scheduling, caching | `quarkus-rest-client-jackson`, `quarkus-scheduler`, `quarkus-cache` | `references/observability-resilience.md` |3536## Pitfalls that cost time3738- Quarkus resolves CDI at build time: an unused bean may be removed. Beans only looked up programmatically need `@Unremovable`.39- Do not read or write public fields of a normal-scoped bean (`@ApplicationScoped`) from another bean or test: you hit the client proxy, not the instance (verified: a counter field read through the proxy returned 0). Use methods.40- Do not block on the event loop (`@NonBlocking` methods, `Uni`/`Multi` return types running on I/O threads). Remove any existing `@NonBlocking` from the method (combining it with `@Blocking` or `@RunOnVirtualThread` fails the build), then add `@Blocking` or `@RunOnVirtualThread` (see `references/reactive-messaging.md`).41- Changes to build-time properties need a rebuild; run-time properties can be overridden by env vars (`QUARKUS_DATASOURCE_JDBC_URL`).42- Do not configure URLs for databases/brokers/Keycloak in `%dev`/`%test`: that disables Dev Services.43- `drop-and-create` schema management is for dev/test only; use Flyway or Liquibase for production.4445Verified on Quarkus 3.40.1 and 3.27.6 (Java 21 target, Maven) with a scaffolded app and `mvn verify` (15 tests: REST+validation+mapper, OpenAPI, config mapping, Panache on PostgreSQL Dev Services, Kafka Dev Service round trip, Keycloak Dev Service tokens, health, metrics, fault tolerance, cache, scheduler). Re-check names against the project's version.