create-quarkus-project

Create a Quarkus Project

1. Detect the environment

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):

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):

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

./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
• Database (Dev Services, Hibernate, Flyway/Liquibase)
• Security basics
• Container images
• Local runtime insights (BootUI)

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/