Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 66 ยท Getting Started

Creating a Project

Create a Spring Boot project with Spring Initializr, understand pom.xml and build.gradle, the wrapper, the folder layout and DevTools.

Every Spring Boot project starts the same way: you describe what you want on a web form, download a small zip, and open it in your IDE. The zip contains a build file, a wrapper script, a main class and an empty test. Understanding what each of those files does saves hours later, because most "Spring problems" in a first week are really build or layout problems.

In this lesson you will create a project with Spring Initializr, read a pom.xml and a build.gradle line by line, learn the standard folder structure and see what DevTools does. Spring and the build tools cannot run in our sandbox, so build files are read-only; the TryIt blocks are Java stand-ins that print a project tree and generate a build file.

Spring Initializr

Spring Initializr is the official project generator, a web app at start.spring.io. The same generator is built into IntelliJ IDEA, VS Code (Spring Boot extensions), Eclipse-based Spring Tools and the spring command-line tool. You choose:

  • Project: Maven or Gradle (Groovy or Kotlin DSL).
  • Language: Java, Kotlin or Groovy. This track uses Java.
  • Spring Boot version: the newest stable release unless you have a reason to pick another.
  • Group and Artifact: your coordinates, for example group com.example and artifact demo. The group becomes the base Java package.
  • Packaging: Jar (the default and almost always right) or War (only for deploying into an external servlet container).
  • Java version: 17 is the minimum for Boot 3 and 4; choose the newest LTS you have installed.
  • Dependencies: the starters you need, such as Spring Web, Validation, Spring Data JPA, H2 Database and Spring Boot DevTools.

Pressing Generate downloads demo.zip. Unzip it and you have a complete, runnable project.

From form to running app

Choose Build tool, Java version and starters.
Generate Download and unzip the project.
Open Import it in your IDE as Maven or Gradle.
Run Start the main class or use the wrapper.
1 / 2

The folder structure

Maven and Gradle share one layout, called the standard directory layout. Tools and IDEs rely on it, so do not invent your own.

TEXT
demo/
โ”œโ”€โ”€ pom.xml                      (or build.gradle + settings.gradle)
โ”œโ”€โ”€ mvnw, mvnw.cmd               (or gradlew, gradlew.bat)
โ”œโ”€โ”€ .mvn/wrapper/                (or gradle/wrapper/)
โ”œโ”€โ”€ .gitignore
โ””โ”€โ”€ src/
    โ”œโ”€โ”€ main/
    โ”‚   โ”œโ”€โ”€ java/com/example/demo/DemoApplication.java
    โ”‚   โ””โ”€โ”€ resources/
    โ”‚       โ”œโ”€โ”€ application.properties
    โ”‚       โ”œโ”€โ”€ static/          (css, js, images served as-is)
    โ”‚       โ””โ”€โ”€ templates/       (server-side HTML templates)
    โ””โ”€โ”€ test/
        โ””โ”€โ”€ java/com/example/demo/DemoApplicationTests.java

Rules worth remembering:

  • Production code lives in src/main/java, resources (configuration, templates, static files) in src/main/resources, tests in src/test.
  • The package of DemoApplication is the root package. Component scanning only looks in that package and its sub-packages, so put your controllers and services below it (com.example.demo.web, com.example.demo.service, and so on). A class in a sibling package such as com.example.other will not be found.
  • static/ and templates/ are conventions Boot reads automatically; you will use them in later lessons.

The next TryIt builds this tree from a list of paths and prints it, which is a tiny model of how an IDE or the tree command shows a project.

Java Print a project tree

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.

Anatomy of a Maven pom.xml

Maven describes the project in pom.xml. This is what Initializr generates for a web project (shortened, read-only):

XML
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>

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

  <groupId>com.example</groupId>
  <artifactId>demo</artifactId>
  <version>0.0.1-SNAPSHOT</version>

  <properties>
    <java.version>21</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-devtools</artifactId>
      <scope>runtime</scope>
      <optional>true</optional>
    </dependency>
  </dependencies>

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

The parts that matter:

  • The parent. spring-boot-starter-parent brings in the BOM (bill of materials): a managed list of compatible versions for hundreds of libraries. That is why the dependencies below have no <version>. The parent also sets the Java compiler level from java.version, UTF-8 encoding, and sensible plugin configuration. The next lesson, Starters and Dependency Management, digs into how this works.
  • Coordinates. groupId, artifactId and version identify your project. SNAPSHOT means "in development".
  • Dependencies. Each starter is one dependency. In Boot 4 the web starter is spring-boot-starter-webmvc; Boot 3 projects and many older tutorials use spring-boot-starter-web for the same job.
  • The Boot plugin. spring-boot-maven-plugin repackages your jar into an executable "fat jar" and adds goals such as spring-boot:run.

The same project in Gradle

Gradle expresses the same information as code (read-only):

GROOVY
plugins {
    id 'java'
    id 'org.springframework.boot' version '4.0.0'
    id 'io.spring.dependency-management' version '1.1.7'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-webmvc'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

The org.springframework.boot plugin plays the role of the Maven plugin, and io.spring.dependency-management imports the BOM so versions can be omitted. developmentOnly keeps DevTools out of the production jar. A second file, settings.gradle, holds the project name.

Which build tool should you pick? Maven is declarative and uniform: nearly every Java developer can read any pom.xml. Gradle is faster on big builds and more flexible, at the cost of more learning. Both are fully supported, and the Spring code you write is identical.

The wrapper

Notice mvnw and gradlew. The wrapper is a small script plus a properties file that downloads the exact build-tool version the project needs. You run ./mvnw spring-boot:run (or mvnw.cmd on Windows) and nobody has to install Maven first. Commit the wrapper to Git: it guarantees that you, your teammate and the CI server build with the same version.

TEXT
./mvnw spring-boot:run      # Maven: start the application
./mvnw test                 # Maven: run the tests
./mvnw clean package        # Maven: build target/demo-0.0.1-SNAPSHOT.jar

./gradlew bootRun           # Gradle: start the application
./gradlew test
./gradlew build             # build/libs/demo-0.0.1-SNAPSHOT.jar

DevTools

spring-boot-devtools is a development-only helper. When you rebuild (Ctrl+F9 in IntelliJ, or save in a Maven/Gradle-aware editor), it restarts the application using a fast two-classloader trick: your own classes are reloaded, library classes stay loaded. It also enables a LiveReload server, turns off template caching, and picks relaxed development defaults.

DevTools turns itself off when the application runs from a packaged jar, and the build plugins exclude it from the executable jar by default. Marking it optional (Maven) or developmentOnly (Gradle) keeps it from leaking into other modules as well.

DevTools in depth

What triggers a restart. DevTools watches the application's classpath. When a class or a classpath resource changes, it restarts the application. A restart only happens after something rebuilds the files: IntelliJ needs "Build Project" (Ctrl+F9) or "Build project automatically" with the option that lets auto-make run while the application is running, Eclipse and VS Code build on save, and with mvn spring-boot:run you recompile from another terminal. If nothing seems to happen, the usual cause is that nothing was compiled.

Restart versus reload. DevTools uses two class loaders. The base loader holds libraries that never change (Spring, Jackson, drivers). The restart loader holds the classes of your own project. A restart throws away only the restart loader, creates a new one and starts the application context again. That skips the slow part of a cold start (loading and verifying thousands of library classes), so restarts are typically much quicker than launching the program from scratch. Reload is lighter still: for static files and templates, nothing restarts at all. DevTools starts an embedded LiveReload server (port 35729) and, with a browser extension, tells the browser to refresh the page.

By default these paths change without a restart: META-INF/maven, META-INF/resources, resources, static, public, templates, test classes, git.properties and META-INF/build-info.properties. You can adjust that:

PROPERTIES
# add extra directories to watch, or stop watching some paths
spring.devtools.restart.additional-paths=../shared-module/target/classes
spring.devtools.restart.additional-exclude=assets/**
# restart only when this file changes (handy with slow IDE builds)
spring.devtools.restart.trigger-file=.reloadtrigger
# switch automatic restart off but keep LiveReload
spring.devtools.restart.enabled=false

Development defaults. DevTools also changes some properties for you, such as disabling template and static-resource caches (for example spring.thymeleaf.cache=false) and turning on more detailed logging for web requests, so a change to a template shows on the next refresh. If you dislike this, set spring.devtools.add-properties=false.

Settings for every project. Personal preferences belong in a file in your home directory, not in each project: ~/.config/spring-boot/spring-boot-devtools.properties (or .yml) applies to every DevTools application on your machine. Typical entries are a longer spring.devtools.restart.poll-interval or a global trigger-file name.

Known limits. Restart works best with simple applications. Because the restart loader is new each time, a class that is shared across the two loaders can fail with a ClassCastException. If a library inside your own multi-module project behaves oddly, list it in META-INF/spring-devtools.properties (for example restart.include.my-module=/my-module-.*\.jar) so it is reloaded with your code. Disable restarts completely with System.setProperty("spring.devtools.restart.enabled", "false") before SpringApplication.run when you debug a class-loading problem.

Remote DevTools can push local changes to an application running elsewhere (set spring.devtools.remote.secret, build the jar with DevTools included, and start RemoteSpringApplication locally). It is meant for a development server only: never enable it on a production system.

The stand-in below applies the real default exclusion list to a list of changed files and decides what happens: restart, reload only, or nothing. It is a model of the rule, not of DevTools' file watcher.

Java Does this change restart the app?

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.

Notice that application.properties restarts the application: it is a classpath resource outside the excluded directories, and Boot reads it only once at startup.

To close the loop, the last TryIt generates both build files from one small model: the same information, two syntaxes.

Java One model, two build files

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.

This is a stand-in for what Initializr does: it holds your choices in a model and renders them into the build file of your choice. The real tool also checks which starters exist for your Boot version.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why do the dependencies in a generated pom.xml usually have no version?

    The parent POM imports a bill of materials that lists a tested version for each library, so you can leave the version out.
  2. 2. Where does component scanning look for your classes?

    Scanning starts at the package of the main class. A class in a sibling package is not found unless you configure extra scan paths.
  3. 3. What is the purpose of the Maven or Gradle wrapper?

    The wrapper scripts make builds reproducible without installing a specific Maven or Gradle version first.
  4. 4. What does DevTools do?

    DevTools is a development convenience (fast restart, LiveReload, no template caching). It switches itself off in a packaged jar.

Summary

  • Spring Initializr (start.spring.io, or your IDE) generates a ready-to-run project from your choices.
  • Maven and Gradle use the same standard layout: code in src/main/java, resources in src/main/resources, tests in src/test.
  • spring-boot-starter-parent (Maven) or the Boot and dependency-management plugins (Gradle) supply managed versions, so starters need none.
  • Keep your classes under the root package of the main class; scanning does not look elsewhere.
  • Commit the wrapper (mvnw/gradlew) so every machine builds the same way.
  • DevTools gives fast restarts in development and is excluded from production jars.

Next: Your First Application.