Skip to content
javahacks.dev
Spring Boot

Create Spring Boot Project With Maven Step by Step

Create a Spring Boot project with Maven using Spring Initializr, curl or an IDE, and read the parent POM, starters and wrapper it generates.

6 min read
Summarize in AI
Flat illustration of a dependency tree and build phases, with the Apache Maven, Docker and GitHub Actions logos.

Every Spring Boot project is a Maven or Gradle build with a handful of dependencies and one class that has a main method. Spring Initializr generates that skeleton so the versions line up, and there are three ways to get it. This post creates a project with Maven using Spring Boot 4 and Java 25, reads the generated pom.xml once so you know what each part does, and covers the first problems people hit. When the project runs, the tutorial takes it to a working API.

Option 1: the website

Go to start.spring.io and choose Project: Maven, Language: Java, the current stable Spring Boot version, Packaging: Jar, and the Java version you run. Fill in the Group, such as dev.javahacks, and the Artifact, such as orders. Add the dependencies you need now, for example Spring Web, Validation and Actuator, and press Generate. Unpack the zip into your workspace.

Choose Jar packaging unless you deploy to an external servlet container. Boot's embedded server is the default and the simpler path, and a WAR adds a configuration step you will not need.

Pick dependencies conservatively. Each one is a starter that brings a set of libraries and, often, auto-configuration that changes behavior. Adding a data starter without a database configured, for example, makes the application fail at startup, which is a good reason to add things when you need them and not on the first day.

Option 2: curl

The same service answers on the command line, which is handy for scripts and for documentation that must be reproducible:

Shell
curl https://start.spring.io/starter.zip \
  -d type=maven-project -d language=java \
  -d groupId=dev.javahacks -d artifactId=orders \
  -d javaVersion=25 -d dependencies=web,validation,actuator \
  -o orders.zip
unzip orders.zip -d orders && cd orders

The parameters are the same ones the website sends. A team can keep this command in its onboarding notes, and a new service starts the same way every time. The dependencies value is a comma-separated list of the identifiers shown on the website.

Option 3: the IDE

IntelliJ IDEA Ultimate, VS Code with the Spring extension pack, and Spring Tools for Eclipse all wrap the same service in a wizard. The wizard produces the same project, and the choice is about where you already work. The one advantage over the website is that the IDE imports the project immediately.

What was generated

Text
orders/
  mvnw, mvnw.cmd, .mvn/wrapper/
  pom.xml
  src/main/java/dev/javahacks/orders/OrdersApplication.java
  src/main/resources/application.properties
  src/test/java/dev/javahacks/orders/OrdersApplicationTests.java

The class OrdersApplication is the entry point, and its package is the root that component scanning starts from. Put your classes in that package or below it. application.properties starts empty, and it is where every setting goes. The test class checks that the application context starts, which is a small test with a large job: it fails whenever the wiring is broken.

The pom, read once

pom.xmlXML
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>4.0.0</version>
  <relativePath/>
</parent>

<properties>
  <java.version>25</java.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
  </plugins>
</build>

The parent does four jobs. It manages the versions of Spring and the hundreds of libraries Boot integrates, which is why no starter has a <version>. It sets the Java level and the compiler options. It configures plugins with sensible defaults. And it makes resource filtering use @...@ placeholders so Maven does not clash with Spring's ${...}. Upgrading Boot is then a change to one number.

A dependency version you add yourself overrides the managed one. That is sometimes needed for a security patch, and it is also how a mismatch between libraries begins, so treat each override as something to review. If you cannot use the parent because your organization already has its own, import the Boot bill of materials in dependencyManagement instead, as explained in Maven BOMs and dependency management.

A starter is not a library. It is a dependency whose only content is more dependencies, chosen to work together: spring-boot-starter-web brings Spring MVC, Jackson, validation support and an embedded Tomcat. That is why a single line can replace a page of version management.

Run it and package it

Shell
./mvnw spring-boot:run
./mvnw package
java -jar target/orders-0.0.1-SNAPSHOT.jar

The first command runs the application from the build, which is what you use while developing. The second builds an executable jar in target/, and the third runs it. The jar is "fat": the Boot plugin repackages it with its dependencies inside, so java -jar is all a server needs.

mvnw is the Maven wrapper. It downloads the Maven version recorded in .mvn/wrapper/maven-wrapper.properties on first use, so a teammate or a CI server needs only a JDK. Commit the wrapper files to the repository, and use ./mvnw everywhere, not mvn. See pinning the Maven version. On Windows the script is mvnw.cmd.

The first problems people meet

If the build stops with a message that the release version is not supported, the JDK on your PATH is older than java.version. Run java -version and ./mvnw -v, which shows the JDK Maven is using, and fix the mismatch, a case covered in invalid target release.

If startup fails complaining that it cannot determine a database driver, you added a data starter before configuring a database. Either configure the URL or remove the starter for now, as described in failed to configure a DataSource.

If the application starts and exits at once, nothing keeps the JVM alive. That happens when the web starter is missing, because there is no server thread. Check the dependency list.

Project layout decisions worth making now

Three small decisions are cheap on day one and expensive later. Choose the group id and base package carefully, because the package is baked into every class and renaming it across a codebase is tedious. Use a name you own, usually a reversed domain, not com.example, which tends to survive into production. Decide the Java baseline deliberately: Boot 4 supports several, and a library you publish should compile to the oldest one its users run, while an application can use the newest. And keep the -SNAPSHOT suffix on the version until you release, since Maven treats snapshots specially and CI servers rely on that.

A last habit: commit immediately after generation, before you edit anything. The first commit then contains exactly what Initializr produced, and a later git diff shows what you changed, which helps when you upgrade Boot and want to compare against a freshly generated project of the new version.

When this is not the route you want

Gradle users have an equivalent flow, described in creating a project with Gradle. Teams with strict dependency policies often mirror Initializr inside the company, so new projects start from approved versions. The reference for the build plugin is the Spring Boot Maven plugin documentation, and the Initializr API describes every parameter you can pass.

Also inDevOps
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.