Skip to content
javahacks.dev
Spring Boot

How to Create a Spring Boot Gradle Project From Scratch

Create a Spring Boot Gradle project with Initializr, read the generated build file with the Spring Boot plugin and dependency management plugin, and run it.

6 min read
Summarize in AI
Flat illustration of a start button surrounded by Spring Boot starters, with the Spring Boot, Gradle, Docker and Apache Maven logos.

A Spring Boot project on Gradle is the same application as the Maven one, with a different build file and a different feel while building. This guide creates one from scratch with Spring Boot 4, Gradle 9 and JDK 25, explains the three parts of the build file that do the work, and covers the mistakes that cost people the first hour: the wrong jar, a missing launcher and a toolchain that quietly picks the wrong JDK.

Generate the project

Shell
curl https://start.spring.io/starter.zip \
  -d type=gradle-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

Use type=gradle-project-kotlin for the Kotlin DSL, or pick Gradle Kotlin under Project on the start.spring.io form. The Groovy DSL is shorter to read for a first build; the Kotlin DSL gives IDE completion and compile-time errors in the build script, which many teams prefer once a build grows. Either produces the same project, and a later move between them is mechanical. The generated archive also contains the Gradle wrapper, so no local Gradle installation is needed.

The build file

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

group = 'dev.javahacks'
version = '0.0.1-SNAPSHOT'

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

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

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

Three parts do the real work. The Spring Boot plugin defines bootRun for development and repackages the output as bootJar. The dependency management plugin imports the Boot BOM, which is why spring-boot-starter-web carries no version: the BOM pins it, and every other Spring and third-party library it manages, to a tested set. And the toolchain block tells Gradle to find or download a JDK 25 for compilation and tests, even if JAVA_HOME points at something older. Without it, a build that works on one laptop fails on another with an error about the class file version.

Run, test and package

Shell
./gradlew bootRun
./gradlew test
./gradlew bootJar
java -jar build/libs/orders-0.0.1-SNAPSHOT.jar

bootRun starts the application from the build output, which is quick for the edit and run loop. bootJar produces an executable archive with the dependencies nested inside. The plain jar task produces a thin archive without them that cannot run on its own, and it also lands in build/libs. People copy the wrong one and get a "no main manifest attribute" error. Spring Boot's plugin disables the plain jar in recent versions unless you ask for it, but old build files may still carry it. Always use the wrapper script, because it runs the Gradle version recorded in gradle/wrapper/gradle-wrapper.properties; the repository, not the machine, decides the version.

Adding dependencies

groovy
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
runtimeOnly 'org.postgresql:postgresql'
developmentOnly 'org.springframework.boot:spring-boot-devtools'

The configuration names carry meaning. implementation puts a library on the compile and runtime classpath of this module only. runtimeOnly is for libraries needed to run but never compiled against, which suits JDBC drivers. developmentOnly keeps DevTools out of the packaged jar, so production never restarts itself on a file change. Adding a starter that needs a database makes the application fail at startup until one is configured, a failure explained in failed to configure a DataSource.

The first hour's common failures

A missing junit-platform-launcher line makes the tests fail on Gradle 9 with a message that the launcher is not on the classpath; the generated file includes it, but older build files do not. A toolchain request for a JDK that Gradle cannot download offline fails with a message listing the locations it searched. And running gradle instead of ./gradlew uses whatever version is installed, which may differ from the wrapper and produce different dependency resolution. If a build downloads dependencies on every run, check that the Gradle build cache and a local cache directory are not wiped between runs.

Reading the build when something goes wrong

Gradle prints very little by default, and the first useful flags are worth knowing on day one. ./gradlew build --scan publishes a build scan to a hosted report if you accept its terms, but without that, --info shows which tasks ran and why one was skipped, and --stacktrace gives the full cause of a failure. ./gradlew dependencies --configuration runtimeClasspath prints the resolved dependency tree, which answers most "why is this version here" questions, and the deeper version of that is in Gradle dependency insight.

Two habits save time. Run ./gradlew build before pushing, since it runs the tests and the jar packaging together, which is what CI will do. And commit the wrapper files: gradlew, gradlew.bat and the gradle/wrapper directory. A repository without them forces every contributor and every CI image to install Gradle and hope it matches.

Version catalogs when the build grows

One application with five dependencies does not need a catalog. Once several modules repeat the same coordinates, move them into gradle/libs.versions.toml, so a version is written once and a dependency is referenced as libs.jackson.databind. The catalog gives IDE completion, a single place for Dependabot or Renovate to edit, and a review diff that shows only the version line. The mechanics are in Gradle version catalogs. Until then, keep the build file short and resist adding custom tasks that the Boot plugin already provides.

Gradle compared with Maven

Gradle caches task outputs and runs incrementally, which makes repeat builds fast, and its build scripts are code, which is both its strength and the cost of learning it. Maven is declarative and uniform, so any Maven project looks like any other. For a Spring team the choice is mostly about familiarity and the size of the build. The comparison is discussed in the Maven tutorial, and the Maven version of this setup is in creating a project with Maven.

Upgrading the build later

When Spring Boot releases a new version, change the plugin version in build.gradle, run ./gradlew build and read the deprecation warnings before anything else. Upgrade Gradle through the wrapper in a separate commit, so a failure points at one change. The Spring Boot release notes list removed properties, and the spring-boot-properties-migrator dependency prints a warning at start-up for every key that moved, which is the quickest way to find stale configuration.

When the single-module layout stops fitting

In a multi-project build the Spring Boot plugin goes only on the module that is the application, and libraries use the java-library plugin so their dependencies are exposed correctly. If dependency resolution fails, read Gradle could not resolve all files. The plugin is documented in the Spring Boot Gradle plugin reference, the next step for the code is the first-API tutorial, and the Gradle toolchains documentation explains how the JDK is located.

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.