Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 36 ยท Getting Started

Creating a Quarkus Project

Create your first Quarkus project with the CLI, Maven or code.quarkus.io, understand the generated files, the pom.xml and the standard directory layout.

Every Quarkus journey starts with a generated project. You do not write the build file by hand: you pick a build tool, a group and artifact name and a few extensions, and a generator produces a working skeleton. There are three common ways to do it, and all three give the same result.

You need a JDK (17 or newer; 21 or 25 is a good choice) and either Maven or Gradle. Quarkus projects ship a wrapper (mvnw or gradlew), so you do not even have to install the build tool yourself. In this lesson you will create a project, walk through every generated file and learn how the layout maps to what Quarkus does. The commands are real; the runnable examples are stand-ins that model project structure and extension selection.

Three ways to generate a project

1. The Quarkus CLI. Install it once (with SDKMAN, Homebrew, Scoop or JBang) and create a project in one line:

Terminal
quarkus create app org.acme:getting-started \
    --extension='rest-jackson' \
    --no-code
cd getting-started

--no-code skips the sample classes. The CLI can also add and remove extensions later and start dev mode: quarkus extension add hibernate-validator, quarkus dev.

2. The Maven plugin. No install needed apart from Maven:

Terminal
mvn io.quarkus.platform:quarkus-maven-plugin:3.27.0:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=getting-started \
    -Dextensions='rest-jackson'

Replace the version with the current Quarkus platform release.

3. The web generator at code.quarkus.io. Tick extensions in the browser, press Generate and download a zip. This is the friendliest way to explore the extension list, and the page shows the exact command line it is equivalent to.

The generated layout

After generation you get a standard Maven project:

Text
getting-started/
  pom.xml
  mvnw, mvnw.cmd, .mvn/
  src/
    main/
      java/org/acme/GreetingResource.java
      resources/
        application.properties
        META-INF/resources/index.html
      docker/
        Dockerfile.jvm
        Dockerfile.native
        Dockerfile.native-micro
        Dockerfile.legacy-jar
    test/
      java/org/acme/GreetingResourceTest.java
      java/org/acme/GreetingResourceIT.java
  README.md

Each part has a purpose:

Path Purpose
pom.xml Dependencies, the Quarkus BOM and the Quarkus Maven plugin
src/main/java Your application code
src/main/resources/application.properties Configuration, empty at first
src/main/resources/META-INF/resources Static files, served at / (for example index.html)
src/main/docker Ready-made Dockerfiles for JVM and native builds
src/test/java @QuarkusTest tests and native integration tests (*IT)

Anything in META-INF/resources is served as a static web resource, so a quick front end can live right inside the project.

Reading the pom.xml

Here is the important part of a generated pom.xml, trimmed:

XML
<properties>
  <maven.compiler.release>21</maven.compiler.release>
  <quarkus.platform.group-id>io.quarkus.platform</quarkus.platform.group-id>
  <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
  <quarkus.platform.version>3.27.0</quarkus.platform.version>
</properties>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>${quarkus.platform.group-id}</groupId>
      <artifactId>${quarkus.platform.artifact-id}</artifactId>
      <version>${quarkus.platform.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-jackson</artifactId>
  </dependency>
  <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-arc</artifactId>
  </dependency>
  <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-junit5</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

Three things to notice:

  1. A BOM (bill of materials) is imported, so you never write versions next to individual Quarkus dependencies. Hibernate, Jackson, Vert.x and all the extensions are tested together at one version.
  2. Dependencies are extensions (quarkus-*). quarkus-arc is the CDI container; quarkus-rest-jackson brings REST plus JSON support.
  3. The quarkus-maven-plugin (in the <build> section) is what runs dev mode and produces the runnable application at mvn package.

Never mix Quarkus extension versions by hand. If you see a version number inside a quarkus-* dependency, something is wrong, and it should come from the BOM.

Building and running

Terminal
./mvnw quarkus:dev        # development mode, hot reload
./mvnw package            # build target/quarkus-app/
java -jar target/quarkus-app/quarkus-run.jar

The package step produces a folder target/quarkus-app/ with quarkus-run.jar and a lib/ directory, not a single "fat jar". This layout starts faster and caches better in container layers. If you want a single jar, set quarkus.package.jar.type=uber-jar in application.properties.

A project model

The next stand-in models what the generator does: it takes a coordinates string and a list of extension names and prints the files and pom dependency lines it would produce. It teaches the naming convention (rest-jackson becomes quarkus-rest-jackson) and the layout.

Java Stand-in: a tiny project generator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Adding extensions later

You are never locked in. To add Hibernate Validator later, either add the dependency to pom.xml or run:

Terminal
./mvnw quarkus:add-extension -Dextensions="hibernate-validator"
# or, with the CLI
quarkus extension add hibernate-validator
quarkus extension list --installable

The next lesson covers what an extension really is. For now remember that "adding a feature" in Quarkus means "adding one dependency".

Choosing Java, Maven or Gradle, and Kotlin

Quarkus supports Maven (the default), Gradle, Java and Kotlin (and Scala). Pick what your team uses. This track uses Maven and Java 21 syntax. With the CLI you can use --gradle or --kotlin, for example quarkus create app org.acme:demo --gradle --kotlin.

The second stand-in checks a project's setup the way you should check it yourself, looking for the most frequent beginner problems: a Java version that is too old and a hard-coded extension version.

Java Stand-in: a project sanity checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Keep application.properties small at first. Quarkus works with almost no configuration, and every property you add should solve a problem you actually have.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does a generated pom.xml import the Quarkus BOM?

    The BOM pins the versions of Quarkus and the libraries it integrates, so extension dependencies need no version numbers of their own.
  2. 2. Where do static files such as index.html go so they are served at the root path?

    Quarkus serves everything under META-INF/resources as static content.
  3. 3. What does ./mvnw package produce by default?

    The default is the fast-jar layout. A single uber-jar needs quarkus.package.jar.type=uber-jar.
  4. 4. How do you add the Hibernate Validator feature to an existing project?

    Features are extensions, added with one dependency (or quarkus extension add hibernate-validator).

Summary

  • Create projects with the Quarkus CLI, the Maven plugin or code.quarkus.io.
  • The skeleton has a pom.xml with the BOM, src/main/java, application.properties, static resources, Dockerfiles and tests.
  • Features are extensions named quarkus-*; versions come from the BOM.
  • ./mvnw quarkus:dev runs development mode; ./mvnw package builds target/quarkus-app/.

Next: Your First Endpoint and Live Coding