Docs

Docs

Starting a Vaadin Project with Gradle

How to create a Vaadin project with Gradle.

Gradle 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. For information about using Gradle, see the Gradle User Manual.

Note
Requirements
The Vaadin Gradle plugin requires Java 21 or later and Gradle 8.14 or later. See Supported Technologies 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.

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. 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.

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 is a web application project skeleton that uses Spring Boot. It’s packaged as an executable JAR file.

Source code
terminal
git clone https://github.com/vaadin/base-starter-spring-gradle my-project

Gradle Starter

The Gradle Starter 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.

Source code
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.

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.

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:

Source code
gradle.properties
vaadinVersion=25.4.0-alpha1

The version of the plugin is then set in settings.gradle:

Source code
settings.gradle
pluginManagement {
    plugins {
        id 'com.vaadin' version "${vaadinVersion}"
    }
}

See the list of releases on GitHub 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.

The build.gradle file applies the plugin without a version, imports the BOM, and adds the Vaadin dependencies:

Source code
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'
}
groovy
groovy
groovy

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, 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 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:

Source code
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. 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:

Source code
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:

Source code
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 for more information on using Gretty. For issues when running the application in development mode, see Gradle Configuration Properties - Known Issues for possible solutions.

Building for Production

A production build bundles and optimizes the frontend resources, as described in Deploying to Production.

To build a Spring Boot application for production, run the bootJar task:

Source code
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:

Source code
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 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