--- applyTo: '**/*.java, **/application*.properties, **/application*.yml, **/application*.yaml, **/pom.xml, **/build.gradle, **/build.gradle.kts' description: 'Quarkus development standards and instructions' --- - Apply these instructions only when the project uses Quarkus (`io.quarkus` dependencies or the Quarkus Maven/Gradle plugin). - Check the project's existing Quarkus and Java versions (pom.xml, build.gradle, `quarkus.platform.version`) before suggesting changes; keep them unless asked to upgrade. For new projects target the recommended stream from https://code.quarkus.io/api/streams (3.40 at the time of testing; 4.0 is still beta) and Java 21+ (Java 17 minimum). Never hard-code a patch version in advice; use the Quarkus BOM. ## Dependencies and build - Add features through Quarkus extensions (`./mvnw quarkus:add-extension -Dextensions=...` or `quarkus extension add`), versions managed by the platform BOM. - Use Quarkus REST (`quarkus-rest`, `quarkus-rest-jackson`) for new projects and explicit migrations. In an existing RESTEasy Classic (`quarkus-resteasy*`) project keep that stack: the two are incompatible and mixing them fails the build. - Use `./mvnw quarkus:dev` (or `./gradlew quarkusDev`) for development; keep the Maven/Gradle wrapper. ## CDI and code - Use constructor injection; `@Inject` is optional on a single constructor. Avoid field injection in production code. - Prefer `@ApplicationScoped` beans; use `jakarta.*` imports only. - Use records for DTOs. Keep REST resources thin and delegate to services. - Use `@ConfigMapping` interfaces for grouped, typed configuration; `@ConfigProperty` for single values. Never hard-code secrets; use env vars or a secret store, and profiles (`%dev`, `%test`, `%prod`). - Use `quarkus.log.*` and JBoss Logging (or SLF4J) for logging. ## REST and validation - Return explicit status codes and map errors centrally rather than try/catch in each resource. In Quarkus REST projects use `RestResponse`/`Response`, `@ResponseStatus` and `@ServerExceptionMapper`; in RESTEasy Classic projects these are unavailable, so use Jakarta REST `Response` and an `ExceptionMapper` annotated `@Provider`. - Validate input with Hibernate Validator (`quarkus-hibernate-validator`, `@Valid`). - Add `quarkus-smallrye-health` and metrics (`quarkus-micrometer-registry-prometheus`, or another Micrometer registry extension; `quarkus-micrometer` alone exports nothing) for production services; expose them only to trusted networks. ## Data - Use Hibernate ORM with Panache (`quarkus-hibernate-orm-panache`); prefer the repository pattern (`PanacheRepository`) for non-trivial domains, active record for simple ones. - Put `@Transactional` on service or resource methods that modify data; paginate list queries. - Manage schema with Flyway or Liquibase in production, not `drop-and-create`. - Rely on Dev Services for databases and brokers in dev/test; do not configure URLs for them in `%dev`/`%test`. ## Security - Use `quarkus-oidc` (or `quarkus-smallrye-jwt`) for authentication, and `@RolesAllowed`/`quarkus.http.auth.permission.*` for authorization. Secure endpoints by default. ## Testing - Use `@QuarkusTest` with RestAssured for application tests, `@QuarkusIntegrationTest` for packaged jar/native/container tests, and `@InjectMock` for CDI mocks. - Use Dev Services and `QuarkusTestResourceLifecycleManager` for external dependencies; use continuous testing in dev mode. - Run `*IT` tests with `./mvnw verify -DskipITs=false` (Failsafe; the generated pom sets `skipITs=true`), not `test`. Test artifacts are `quarkus-junit` (3.31+) or `quarkus-junit5` (older); keep what the project uses. ## Avoid - Reflection-heavy libraries without `@RegisterForReflection` when targeting native. - Blocking calls on the event loop (use `@Blocking` or virtual threads with `@RunOnVirtualThread`). - Swallowing exceptions or hard-coding configuration values. Upgrading Quarkus: run `quarkus update` () and read the version's migration guide at (change the version) before editing. --- Source: awesome-copilot (github/awesome-copilot) https://github.com/github/awesome-copilot/blob/cb64ad12e32737ae764becd6885462e9b4c7cb00/instructions/quarkus.instructions.md MIT License Copyright GitHub, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.