AutoGineer
Generated banner for Quarkus Application Development
Generated logo for Quarkus Application Development

Quarkus Application Development

GitHubOfficialFirst committed by jduboisDistributed by GitHub

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

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.
— the description by jdubois

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to developing application code within a Quarkus project. It covers the integration of essential extensions such as Hibernate ORM with Panache, REST services, security via OIDC, observability, and messaging with Kafka. The skill emphasizes adherence to Quarkus-specific patterns, such as build-time CDI resolution, proper configuration management, and the use of Dev Services for testing, while ensuring developers avoid common pitfalls like blocking the event loop or hard-coding secrets.

What it does

  • Guides the addition of Quarkus extensions using standard CLI commands.
  • Provides patterns for REST API development, including validation and exception handling.
  • Offers best practices for CDI bean management and configuration using @ConfigMapping.
  • Outlines implementation strategies for observability, resilience, and scheduling.
  • Ensures secure development by advising against hard-coded secrets and promoting OIDC integration.
  • Helps troubleshoot common Quarkus-specific issues like bean removal and event loop blocking.

When to use it

  • When implementing new features or modifying existing logic in a Quarkus application.
  • When integrating new infrastructure dependencies like Kafka or OIDC.
  • When configuring application properties or setting up observability and fault tolerance.
  • When debugging issues related to CDI, bean scopes, or blocking operations.

Advantages

  • Promotes consistent use of Quarkus-idiomatic code and Jakarta EE standards.
  • Reduces development time by providing verified patterns for common integration tasks.
  • Helps maintain application performance by highlighting event loop and blocking constraints.
  • Ensures project stability by leveraging build-time validation and proper configuration management.

Usage examples

“How do I add a REST endpoint that uses Hibernate Panache to fetch data from a database?”
The agent will guide you to add the quarkus-hibernate-orm-panache extension, define a PanacheEntity, and create a REST resource that injects the repository or uses the active record pattern.
“I need to add a scheduled task that runs every hour. How should I implement this?”
The agent will advise using the @Scheduled annotation on a bean method and suggest configuring the interval or cron expression via application properties.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/github/quarkus-application-development/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip quarkus-application-development.zip -d .agents/skills

Documentation by jdubois

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

  1. 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).

  2. 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>.

  3. Ask the user before adding Kafka, OIDC/Keycloak or any new infrastructure dependency (they start containers in dev/test and change deployment needs).

  4. Never use the Spring compatibility extensions (quarkus-spring-*) unless the project already does.

  5. 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.

  6. Use jakarta.* imports, records for DTOs, thin resources delegating to services.

  7. Never hard-code secrets or add credentials to application.properties; see references/config-cdi.md.

Quick decisions

NeedUseDetails
JSON REST APIquarkus-rest-jackson, quarkus-hibernate-validator, quarkus-smallrye-openapireferences/rest.md
Typed config@ConfigMapping; @ConfigProperty for single valuesreferences/config-cdi.md
Beans@ApplicationScoped (default), @Singleton only for plain stateless holdersreferences/config-cdi.md
Databasequarkus-hibernate-orm-panache + JDBC driver, repository patternreferences/persistence.md
Async / blockingImperative by default; @RunOnVirtualThread or Uni when neededreferences/reactive-messaging.md
Messagingquarkus-messaging-kafka (SmallRye Reactive Messaging)references/reactive-messaging.md
AuthN/AuthZquarkus-oidc, @RolesAllowedreferences/security-oidc.md
Opsquarkus-smallrye-health, quarkus-micrometer-registry-prometheus, quarkus-opentelemetry, quarkus-smallrye-fault-tolerancereferences/observability-resilience.md
Outbound HTTP, scheduling, cachingquarkus-rest-client-jackson, quarkus-scheduler, quarkus-cachereferences/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.

Files

references/security-oidc.md

Security: OIDC, roles, JWT

Extension: quarkus-oidc (bearer token for services, authorization code flow for web apps). Ask the user before adding it. Alternative for self-issued tokens: quarkus-smallrye-jwt (mp.jwt.verify.publickey.location, mp.jwt.verify.issuer).

Keycloak Dev Service (verified on 3.40.1 and 3.27.6)

With quarkus-oidc and no quarkus.oidc.auth-server-url, dev/test mode starts Keycloak and imports a quarkus realm with users alice (admin, user) and bob (user), client quarkus-app. First start is slow (about 50 s with image pull). Customize roles:

quarkus.keycloak.devservices.roles.alice=admin,user
quarkus.keycloak.devservices.roles.bob=user

Dev UI (/q/dev-ui, OpenID Connect card) can log in and obtain tokens. For production set %prod.quarkus.oidc.auth-server-url=${OIDC_URL}, %prod.quarkus.oidc.client-id, and credentials.secret from env/secret store; never in git.

Bearer (service) and web-app modes

  • Default quarkus.oidc.application-type=service: expects Authorization: Bearer <jwt>.

  • Browser app: quarkus.oidc.application-type=web-app (session cookie, redirect to IdP). Pair with quarkus.http.auth.permission.* for path rules.

Authorization

@Path("/secure")
public class SecuredResource {
    @Inject SecurityIdentity identity;

    @GET @Path("/me") @Authenticated
    public String me() { return identity.getPrincipal().getName(); }

    @GET @Path("/admin") @RolesAllowed("admin")
    public String admin() { return "admin ok"; }
}

Verified results: no token gives 401; a token for alice gets 200 on /secure/admin; bob gets 403 there and 200 on /secure/me.

  • Secure by default: quarkus.security.jaxrs.deny-unannotated-endpoints=true (not verified here).

  • Fine-grained checks: @PermissionsAllowed("read") with a SecurityIdentity permission checker, or @PermissionChecker methods (quarkus-security); or inject SecurityIdentity and check identity.hasRole(...). Not verified here.

  • JWT claims: inject org.eclipse.microprofile.jwt.JsonWebToken (with quarkus-oidc, @Inject JsonWebToken jwt; jwt.getClaim("email")). Default role lookup: a groups claim wins if present; otherwise Keycloak's realm_access/roles, and resource_access/<quarkus.oidc.client-id>/roles when a client id is configured (a token with non-empty groups uses those even if realm roles exist). Override with quarkus.oidc.roles.role-claim-path.

  • Calling downstream services with the user's token: quarkus-rest-client-oidc-token-propagation; with the service's own identity: quarkus-rest-client-oidc-filter. Not verified here.

Testing

  • Unit-style: @TestSecurity(user = "u", roles = "admin") with quarkus-test-security (verified: 200 for admin, 403 for another role).

  • Real tokens against the Dev Service: quarkus-test-keycloak-server provides io.quarkus.test.keycloak.client.KeycloakTestClient; given().auth().oauth2(new KeycloakTestClient().getAccessToken("alice")) (verified). Also see quarkus-dev-services-and-testing.

  • Keycloak container requires Docker; tests relying on it should be run where containers exist.

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by
GitHub avatar of jduboisjdubois
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/quarkus-application-development · commit 797337f
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
jdubois

AutoGineer is not affiliated with or endorsed by jdubois or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download quarkus-application-development.zip