Quarkus rules
Cursor rules for Quarkus 3 services in Java: Quarkus REST, Panache, config mapping, Dev Services, and native-friendly code.
CursorJava
How to use
Save this as .cursor/rules/quarkus.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.
Note: Review and test before use. Provided as is, without warranty. See Terms.
.cursor/rules/quarkus.mdcDownload ---
description: Quarkus conventions
globs: ["src/main/java/**/*.java","src/main/resources/application.properties"]
alwaysApply: false
---
# Quarkus 3
- Run with `./mvnw quarkus:dev` (live reload, Dev Services start databases/brokers in containers). Test with `./mvnw verify`.
- REST endpoints with Quarkus REST (`@Path`, `@GET`, `@POST`) returning DTO `record`s; validate with Hibernate Validator (`@Valid`, constraint annotations). Map errors with `@ServerExceptionMapper`.
- Beans are CDI: `@ApplicationScoped` services with constructor injection. Avoid `@Singleton` unless you need eager, unproxied beans.
- Persistence with Hibernate ORM Panache: entities or repositories (`PanacheRepository<Order>`), queries like `find("status", Status.OPEN).page(0, 50)`. Writes inside `@Transactional` service methods.
- Schema via Flyway migrations (`src/main/resources/db/migration`), not `drop-and-create` outside dev.
- Config with `@ConfigMapping(prefix = "app")` interfaces; secrets from env or a vault, profiles via `%dev.`/`%prod.` prefixes.
- Use Quarkus extensions (`quarkus ext add rest-client-jackson`) instead of raw libraries when one exists.
- Keep code native-image friendly: avoid runtime reflection and dynamic class loading; register with `@RegisterForReflection` when needed.
- Blocking vs reactive: be consistent per endpoint; annotate `@Blocking`/`@NonBlocking` when mixing, and never block the event loop.
- Health and metrics via `smallrye-health` and Micrometer.
## Done when
`./mvnw verify` passes with `@QuarkusTest` tests (REST Assured for endpoints).