> Markdown version of [Gradle](https://vaadin.com/docs/next/getting-started/starters/gradle). Section index: [llms.txt](https://vaadin.com/docs/next/getting-started/llms.txt)
# Starting a Vaadin Project with Gradle
[Gradle](https://gradle.org/) is a build tool for Java and other JVM languages, and an alternative to Maven. You can use it to manage the dependencies of a Vaadin application, run the application during development, and build it for production.
This page describes how to create a Vaadin project with Gradle, either as a Spring Boot application or as a web application that runs in a servlet container. For the tasks and configuration options of the Vaadin Gradle plugin, see [Gradle Configuration Properties](https://vaadin.com/docs/next/flow/configuration/gradle.md). For information about using Gradle, see the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html).
> **Note: Requirements**
>
> The Vaadin Gradle plugin requires Java 21 or later and Gradle 8.14 or later. See [Supported Technologies](https://vaadin.com/docs/next/compatibility.md) for the other technologies Vaadin supports. The plugin installs Node.js and npm automatically when running the build for the first time if they are missing or the installed version is below the minimum required. If you plan to use Vaadin’s Gradle-based starter projects, there’s no need to install Gradle on your machine. A Gradle Wrapper script is included in starter projects. It manages locally the download and execution of Gradle for your project. For more information on using Gradle Wrapper, see the [Official Gradle Documentation](https://docs.gradle.org/current/userguide/gradle_wrapper.html).
## Creating a Vaadin Project
You can create a Vaadin project with Gradle in the following ways:
- Clone one of the starter repositories described in the next section.
- Generate a Spring Boot project with [Spring Initializr](https://vaadin.com/docs/next/getting-started/starters/spring-initializr.md). Choose Gradle as the build tool and add the *Vaadin* dependency.
- Add the Vaadin Gradle plugin and the Vaadin dependencies to an existing project, as described in [The Build Files](#build-file).
### Cloning a Starter Repository
The following starter repositories are available. The default branch is for the latest Vaadin version. You can find starters for earlier versions in their respective branches.
#### Spring Boot Gradle Starter
The [Spring Boot Gradle Starter](https://github.com/vaadin/base-starter-spring-gradle) is a web application project skeleton that uses Spring Boot. It’s packaged as an executable JAR file.
```terminal
git clone https://github.com/vaadin/base-starter-spring-gradle my-project
```
#### Gradle Starter
The [Gradle Starter](https://github.com/vaadin/base-starter-gradle) is a web application project skeleton that doesn’t use Spring Boot. It’s packaged as a WAR file, to be deployed to a servlet container such as Jetty or Tomcat. During development, it runs in an embedded web server provided by the Gretty plugin.
```terminal
git clone https://github.com/vaadin/base-starter-gradle my-project
```
### Gradle Files in Starter Projects
Gradle-related files are as follows:
- `build.gradle`
The Gradle build file, as described in [The Build Files](#build-file).
- `gradle.properties`
Defines the `vaadinVersion` property, which sets the version of both the Vaadin Gradle plugin and the Vaadin dependencies. To upgrade Vaadin, change the value of this property.
- `settings.gradle`
Sets the version of the Vaadin Gradle plugin from the `vaadinVersion` property.
- `gradlew` and `gradlew.bat`
Gradle Wrapper build scripts for Linux/Mac (`gradlew`) and Windows (`gradlew.bat`). The build scripts enable the project to be built without having Gradle preinstalled. The Gradle version they use is set in `gradle/wrapper/gradle-wrapper.properties`. Since the recommended way to execute any Gradle build is with the help of the Gradle Wrapper, `gradlew` is used instead of `gradle` throughout the documentation. However, the `gradlew` and `gradle` commands can be used interchangeably if you already have Gradle installed and you prefer to use your installed Gradle. You can learn more about the benefits of using Gradle Wrapper in the [Official Gradle Documentation](https://docs.gradle.org/current/userguide/gradle_wrapper.html).
To avoid unnecessary verbosity, only the Unix style of running `./gradlew` is used for the rest of this page. Replace it with `gradlew` if you’re using Windows.
## The Build Files
A Vaadin project applies the Vaadin Gradle plugin and imports the Vaadin bill of materials (BOM), which manages the versions of the Vaadin dependencies. The plugin and the BOM should use the same version. The starter projects define the version once, in `gradle.properties`:
`gradle.properties`
```properties
vaadinVersion=25.4.0-alpha1
```
The version of the plugin is then set in `settings.gradle`:
`settings.gradle`
```groovy
pluginManagement {
plugins {
id 'com.vaadin' version "${vaadinVersion}"
}
}
```
See the [list of releases on GitHub](https://github.com/vaadin/platform/releases) for the latest Vaadin version. To use a pre-release version, you also need to add the Vaadin pre-release repository, as described in [Using Gradle plugin Snapshot Versions](https://vaadin.com/docs/next/flow/configuration/gradle.md#pre-release).
The `build.gradle` file applies the plugin without a version, imports the BOM, and adds the Vaadin dependencies:
**Spring Boot**
```groovy
plugins {
id 'java'
id 'org.springframework.boot' version '4.1.0'
id 'io.spring.dependency-management' version '1.1.7'
id 'com.vaadin'
}
repositories {
mavenCentral()
}
configurations {
developmentOnly
runtimeClasspath {
extendsFrom developmentOnly
}
}
dependencyManagement {
imports {
mavenBom "com.vaadin:vaadin-bom:$vaadinVersion"
}
}
dependencies {
implementation 'com.vaadin:vaadin-spring-boot-starter'
developmentOnly 'com.vaadin:vaadin-dev'
}
```
**Without Spring Boot**
```groovy
plugins {
id 'war'
id 'org.gretty' version '5.0.2'
id 'com.vaadin'
}
repositories {
mavenCentral()
}
dependencies {
implementation enforcedPlatform("com.vaadin:vaadin-bom:$vaadinVersion")
implementation 'com.vaadin:vaadin-core'
if (gradle.startParameter.taskNames.any { it in ['appRun', 'appRunDebug'] }) {
implementation 'com.vaadin:vaadin-dev'
}
}
```
The `java` plugin is optional, as the Vaadin Gradle plugin applies it. To write the application in Kotlin or Groovy, add the corresponding plugin.
The `vaadin-dev` dependency enables [development mode](https://vaadin.com/docs/next/flow/configuration/development-mode.md), which you need when running the application during development. It shouldn’t be packaged into the production build. The Spring Boot build file adds it to the `developmentOnly` configuration, which Spring Boot leaves out of the executable JAR file. Making the runtime classpath extend `developmentOnly` keeps the dependency available when you run the application from an IDE. The other build file adds it only when the application is run with Gretty.
Without Spring Boot, the `war` plugin packages the application as a WAR file, and the Gretty plugin runs it during development. The servlet container provides the Servlet API at runtime. If your code uses the Servlet API directly, add it to the dependencies with `providedCompile 'jakarta.servlet:jakarta.servlet-api:6.1.0'`. See [Running the Application](#running) for how to configure Gretty.
## Running the Application
You run a Spring Boot application during development like any other Spring Boot application: either from the class containing the `main()` method — the one annotated with `@SpringBootApplication` — or with the `bootRun` task of the Spring Boot Gradle plugin:
```terminal
./gradlew bootRun
```
If you’re using a web application without Spring Boot, you can run it during development with the Gretty plugin, which runs the application in an embedded web server. You can do this either in an IDE or from the command line. The plugin is applied in the `plugins` block of the `build.gradle` file, as shown in [The Build Files](#build-file). Use Gretty 5.0 or later: it’s the first version that supports Jetty 12 and Tomcat 11, and earlier versions only run servlet containers that Vaadin doesn’t support.
You can configure Gretty further in an optional `gretty` block:
```groovy
gretty {
contextPath = "/" (1)
servletContainer = "jetty12" (2)
}
```
1. Sets the context path to the root path. The default context path contains the project name, so the URL would be `http://localhost:8080/myproject` — adjusted for whatever your project is named.
2. Sets the servlet container to Jetty 12. Gretty also supports Tomcat 11, with the value `tomcat11`.
The application is started with the `appRun` task:
```terminal
./gradlew appRun
```
The task compiles the application and starts the web server in `http://localhost:8080/` — if the root context path is configured as described earlier.
See the [Gretty project on GitHub](https://github.com/gretty-gradle-plugin/gretty) for more information on using Gretty. For issues when running the application in development mode, see [Gradle Configuration Properties - Known Issues](https://vaadin.com/docs/next/flow/configuration/gradle.md#known-issues) for possible solutions.
## Building for Production
A production build bundles and optimizes the frontend resources, as described in [Deploying to Production](https://vaadin.com/docs/next/flow/production.md).
To build a Spring Boot application for production, run the `bootJar` task:
```terminal
./gradlew clean bootJar
```
The Vaadin Gradle plugin enables production mode automatically for this task. The executable JAR file is written to the `build/libs` directory, and you can run it with `java -jar`.
Without Spring Boot, enable production mode with the `vaadin.productionMode` property and build the WAR file with the `build` task:
```terminal
./gradlew clean build -Pvaadin.productionMode=true
```
The WAR file is written to the `build/libs` directory. You can then deploy it to a servlet container. The build file of the Gradle Starter enables production mode whenever you run the `build` task, so in the starter you can leave out the property.
See [Gradle Configuration Properties - Production](https://vaadin.com/docs/next/flow/configuration/gradle.md#production) for other ways to enable production mode, and for how to package a Spring Boot application as a WAR file.
`FA18F1BF-2C67-4CCF-85A2-C3E4D7AECFDB`