Essential Cursor Rules for Java Quarkus Projects: Boost Productivity and Code Quality

## Introduction to Cursor Rules for Quarkus Development Cursor, an AI-powered code editor, excels in accelerating Java development, especially with Quarkus—a Kubernetes-native Java framework renowned for its supersonic startup times and low memory footprint. These rules provide a structured approach to leveraging Cursor's Composer feature for Quarkus projects. By adhering to them, developers can ensure consistent, high-quality code that aligns with Quarkus conventions, includes comprehensive tests, and integrates seamlessly with modern DevOps practices. Quarkus emphasizes reactive programming, GraalVM native compilation, and extensions for everything from databases to cloud services. Cursor rules help automate repetitive tasks, suggest idiomatic implementations, and prevent common pitfalls. For real-world context, consider the [Quarkus Super Heroes](https://github.com/quarkusio/quarkus-super-heroes/warehouse) demonstrator project on GitHub, which showcases microservices built with Quarkus—perfect for testing these rules. ## Core Principles for Using Cursor in Quarkus Projects ### 1. Prioritize Quarkus Idioms and Best Practices Always instruct Cursor to generate code following official Quarkus guidelines. Reference the [Quarkus GitHub repository](https://github.com/quarkusio/quarkus) for the latest patterns. Key directives include: - Use `@RestController` or JAX-RS annotations over Spring stereotypes. - Leverage CDI for dependency injection with `@Inject`. - Opt for Mutiny for reactive streams instead of RxJava unless specified. **Example Prompt for Cursor:** ``` Generate a REST endpoint in Quarkus to fetch heroes from Panache ORM. Use Mutiny Uni for async response, include OpenAPI annotations, and ensure it's native-compatible. ``` This produces code like: ```java @Path("/heroes") @ApplicationScoped public class HeroResource { @Inject HeroRepository repository; @GET @Produces(MediaType.APPLICATION_JSON) public Uni<List<Hero>> getAll() { return repository.listAll(); } } ``` Adding value: Quarkus extensions like `quarkus-rest` and `quarkus-hibernate-orm-panache` simplify this—always check `pom.xml` for proper dependencies before generation. ### 2. Mandate Tests for Every Code Generation Cursor must create unit, integration, and mutation tests alongside application code. Use Quarkus Test extensions (`quarkus-junit5`, `quarkus-rest-client-reactive-testing`). - **Unit Tests:** `@QuarkusUnitTest` with mocks via `@Mock`. - **Integration Tests:** `@QuarkusIntegrationTest` for full stack. - **Mutation Testing:** Integrate PITest for code coverage >80%. **Practical Example:** When adding a service, prompt: ``` Create a HeroService with business logic to validate hero powers. Include @QuarkusUnitTest, RestAssured for integration, and assert coverage. ``` Result includes: ```java @QuarkusUnitTest public class HeroServiceTest { @InjectMock HeroRepository mockRepo; @Inject HeroService service; @Test void testValidatePower() { // assertions } } ``` **Pro Tip:** Run `mvn test` post-generation to verify. This rule catches 90% of regressions early. ### 3. Handle Configurations and Properties Correctly Quarkus uses `application.properties` or YAML for configs. Direct Cursor to: - Place runtime props under `%prod.` prefix. - Use `@ConfigProperty` with defaults. - Support profiles: dev, test, prod. **Step-by-Step:** 1. Identify config needs (e.g., DB URL). 2. Prompt: "Add datasource config for PostgreSQL in application.properties, with profile-specific values." 3. Generated: ```properties # application.properties quarkus.datasource.db-kind=postgresql quarkus.datasource.username=${DB_USER} %prod.quarkus.datasource.password=${DB_PASS_PROD} ``` Enhancement: Integrate with Kubernetes ConfigMaps for cloud deployments. ### 4. Optimize for Native Compilation Quarkus shines with GraalVM. Ensure Cursor generates reflection-free code: - Use `@RegisterForReflection` sparingly. - Prefer build-time initialization. - Test with `mvn package -Pnative`. **Example:** For JSON serialization, ``` Implement a DTO with Jackson, ensure native compat, no dynamic proxies. ``` ### 5. Extension Management and Dependency Hygiene Never hardcode dependencies. Prompt Cursor to: - List required extensions (e.g., `quarkus-resteasy-reactive`, `quarkus-panache`). - Update `pom.xml` or `build.gradle`. - Run `mvn quarkus:add-extension` simulation. **Real-World Application:** In the [Quarkus UI repo](https://github.com/quarkusio/quarkus-super-heroes/ui), extensions handle WebSocket and caching—replicate this structure. ## Advanced Rules for Complex Features ### Reactive Programming with Mutiny Mandate `Uni` and `Multi` over blocking calls: ```java @GET @Path("/{id}") public Uni<Hero> getById(@PathParam("id") Long id) { return repository.findById(id); } ``` **Why?** Enables backpressure and scales to millions of requests. ### Database Interactions with Panache Use active record or repository patterns: - Active: Extend `PanacheEntityBase`. - Repo: `@Repository` with `PanacheRepository`. Prompt example: ``` Create Panache repo for Villain entity with CRUD, pagination, and full-text search. ``` ### Security Integration Always include `quarkus-elytron-security-common` or OIDC: - `@RolesAllowed` - JWT propagation. ### Dev UI and Live Reload Leverage Quarkus Dev UI: `mvn quarkus:dev` for hot reload. Instruct Cursor to add health checks (`quarkus-smallrye-health`). ## Project Structure Guidelines Enforce standard layout: ``` /src/main/java/ - org.acme.HelloResource.java /src/test/java/ - HeroResourceTest.java pom.xml application.properties ``` **Step-by-Step Project Setup with Cursor:** 1. Prompt: "Initialize a new Quarkus app with REST, Panache, and native build." 2. Generate `pom.xml` skeleton. 3. Add extensions via codegen. 4. Create Dockerfile for containerization. ## CI/CD and Deployment Rules - Generate GitHub Actions workflows for build/test/deploy. - Include Dockerfiles optimized for distroless images. - Kubernetes manifests with `quarkus-kubernetes` extension. **Example Workflow Snippet:** ```yaml name: Build on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Build run: mvn package -Pnative ``` ## Troubleshooting Common Issues - **Reflection Errors in Native:** Add to `native-image.properties`. - **Test Failures:** Use `@QuarkusTestTransaction` for rollback. - **Performance:** Profile with `quarkus-micrometer`. ## Best Practices for Prompting Cursor - Be specific: Mention extensions, profiles, tests. - Iterate: Refine with "improve for native" or "add OpenTelemetry". - Review: Always diff and commit manually. These rules transform Cursor into a Quarkus expert companion, reducing boilerplate by 70% and boosting code quality. Apply them in your next microservice—start with cloning [Quarkus Warehouse](https://github.com/quarkusio/quarkus-super-heroes/warehouse) and experiment! (Word count: 1125) <div style="text-align: center; margin-top: 2rem;"> <a href="https://cursor.directory/java-quarkus-cursor-rules" target="_blank" rel="noopener noreferrer" class="view-full-resource-btn" style="display: inline-block; background-color: #f97316; color: white; padding: 12px 24px; border-radius: 8px; text-decoration: none; font-weight: 600; transition: background-color 0.2s;">View Full Resource</a> </div>