create-quarkus-project - Claude MCP Skill

# Create a Quarkus Project

## 1. Detect the environment

```bash
java -version          # Java 17, 21 or 25 (Quarkus 3.40 recommends 25, 3.27 recommends 21)
quarkus --version      # optional Quarkus CLI
./mvnw -v || mvn -v    # or ./gradlew -v
```

If the folder already contains a Quarkus project (`io.quarkus.platform` BOM, `quarkus-maven-plugin`, or `io.quarkus` Gradle plugin), do NOT scaffold: read its Quarkus version and keep it. For a new project, use the stream marked recommended on https://code.quarkus.io/api/streams (an LTS stream; see also https://quarkus.io/support/), and do not invent a patch version: let the tool pick it. Quarkus 4.0 is still a beta, so do not use it unless asked. If an extension is missing from the recommended stream, the CLI silently picks an older stream; check `quarkus.platform.version` in the generated build file.

## 2. Scaffold (pick one)

Quarkus CLI (install via https://quarkus.io/get-started/ , e.g. SDKMAN `sdk install quarkus`):

```bash
quarkus create app com.example:demo \
  --extension='rest-jackson,hibernate-orm-panache,jdbc-postgresql,hibernate-validator,smallrye-health' \
  --java=21 --maven        # or --gradle
```

No CLI: Maven plugin (pin the version to the current release from https://quarkus.io/guides/maven-tooling, replace `QUARKUS_VERSION` below with it):

```bash
mvn io.quarkus.platform:quarkus-maven-plugin:QUARKUS_VERSION:create \
  -DprojectGroupId=com.example -DprojectArtifactId=demo \
  -Dextensions='rest-jackson,hibernate-orm-panache,jdbc-postgresql' \
  -DbuildTool=maven        # or gradle
```

Or generate from the https://code.quarkus.io web UI / REST API (`https://code.quarkus.io/d?g=com.example&a=demo&e=rest-jackson&b=MAVEN`) and unzip.

## 3. Choose extensions

| Need | Extension |
|---|---|
| REST + JSON | `rest-jackson` (Quarkus REST; not legacy `resteasy`) |
| Database ORM | `hibernate-orm-panache`, `jdbc-postgresql` |
| Validation | `hibernate-validator` |
| Health / metrics | `smallrye-health`, `micrometer-registry-prometheus` |
| Auth | `oidc` or `smallrye-jwt` |
| OpenAPI | `smallrye-openapi` |
| REST client | `rest-client-jackson` |
| Container | `container-image-jib` (or `container-image-docker`) |

Add later with `quarkus extension add <name>` or `./mvnw quarkus:add-extension -Dextensions=<name>`; `quarkus extension list --installable` lists options.

## 4. Layout and run

```
src/main/java/...          # resources, services, entities
src/main/resources/application.properties
src/main/docker/           # Dockerfile.jvm, Dockerfile.native, ...
src/test/java/...          # @QuarkusTest / @QuarkusIntegrationTest
```

```bash
./mvnw quarkus:dev         # or: quarkus dev / ./gradlew quarkusDev
```

Generated tests include a `*IT` class that Maven skips by default (`<skipITs>true</skipITs>` in the template); run it with `./mvnw verify -DskipITs=false` or `-Dnative`. Dev mode gives live reload, Dev UI at http://localhost:8080/q/dev-ui, Dev Services (auto containers), and continuous testing (press `r`). Package: `./mvnw package` (runnable `target/quarkus-app/quarkus-run.jar`).

## References

- [Configuration](references/configuration.md)
- [Database (Dev Services, Hibernate, Flyway/Liquibase)](references/database.md)
- [Security basics](references/security.md)
- [Container images](references/container-image.md)
- [Local runtime insights (BootUI)](references/local-runtime-insights.md)

Verified (scaffold, `./mvnw verify`, `./gradlew build`, dev mode, Dev Services PostgreSQL, JDK 26 with Java 25 release) on Quarkus 3.40.1 (current recommended LTS stream) and `./mvnw verify` on 3.27.6 (older LTS).

Related skills: `quarkus-dev-services-and-testing`, `quarkus-native-and-container`.

## Upstream sources (read before upgrading)

Fetch the page for the target version; prefer it over this skill when they conflict.

- `quarkus update` (automated upgrade, uses OpenRewrite): <https://quarkus.io/guides/update-quarkus>
- Migration guides, one wiki page per minor: <https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.20> (change the version)
- Release announcements: <https://quarkus.io/blog/>
- LTS policy and current LTS: <https://quarkus.io/blog/lts-releases/>