Start a Project
Gradle is a popular build tool for Java, Groovy, Kotlin, and other projects. It’s an alternative to using Maven, and in many ways much simpler. It’s also more powerful. You can use it to build and run a Vaadin application and manage dependencies during development.
This page describes how to create, compile, and run a Vaadin application using the Vaadin Gradle plugin. The Gretty plugin is used to run an application in an embedded web server.
For information about using Gradle, see the Gradle User Manual.
Requirements
To use the Vaadin Gradle plugin, your environment needs to meet the following requirements:
-
Windows, Mac, or Linux operating system;
-
Java SDK 11 or later;
-
Gradle 5 or 6, which is optional because of the wrapper provided in the starter projects (see https://gradle.org/install on how to install directly); and
-
Node.js and
npm
, which is optional because they can also be installed locally to the project using the Vaadin Gradle plugin.
Note
|
Installing Gradle is Optional
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
The easiest way to create a new project is to clone a starter repository containing an application skeleton.
You can also make a build.gradle
file for any existing Vaadin project, as described in The Build File.
Cloning a Starter Repository
The following starter repositories are available. The default branch is for the latest Vaadin version. You can find older starters with long-term support in their respective branches:
-
https://github.com/vaadin/base-starter-gradle
A simple web application project to be deployed as a WAR package. This example can also be used for Java EE, by changing the servlet dependency to
javax:javaee-api
and perhaps also adding the dependencycom.vaadin:vaadin-cdi
for CDI integration.git clone https://github.com/vaadin/base-starter-gradle my-project
-
https://github.com/vaadin/base-starter-spring-gradle
A web application project skeleton that uses Spring Boot.
git clone https://github.com/vaadin/base-starter-spring-gradle my-project
Starter Project Contents
When it’s been cloned, the project structure should look as follows:
base-starter-gradle
├── frontend // HTML templates and other front-end code
│ └──themes
│ └──my-theme // The application styles
│ └──styles.css
│ └──theme.json
│ └──index.html
├── gradle
│ └──wrapper
│ └──gradle-wrapper.jar // Gradle wrapper sources
│ └──gradle-wrapper.properties
├── src/main
│ └──java
│ └──com.vaadin.starter.skeleton
│ └──AppShell.java // Class for customising the Application Shell,
│ // also known as Bootstrap Page
│ └──GreetService.java // Example data service
│ └──MainView.java // The application skeleton
│ └──resources
│ └──simplelogger.properties // Logging configuration
│ └──webapp
├── build.gradle // Gradle build configuration
├── gradle.properties // System properties and environment variables
├── gradlew // Gradle wrapper build scripts
├── gradlew.bat
├── LICENSE
├── README.md // Build and usage instructions
└── settings.gradle // Gradle build-related settings
Only the contents of base-starter-gradle
— a simple web application starter without Spring Boot — are shown in the preceding figure. However, the Spring Boot-based starter project is a little different, except that it has an additional class annotated with @SpringBootApplication
. If this is the first time you’ve tried Vaadin with Spring Boot, see Using Vaadin with Spring Boot for more information.
The most important files and folders are as follows:
src/main/java/<package>/MainView.java
-
The application view class for the root route, built from components.
src/main/java/<package>/GreetService.java
-
A trivial service object to separate business data and logic from the view.
frontend/src
-
Folder for HTML templates and JavaScript code. See the
README
file inside for more details. frontend/styles/shared-styles.css
-
Application-specific style sheets to style the look of the application.
frontend/styles/vaadin-text-field-styles.css
-
An example of how to modify the style of the
TextField
component. build.gradle
-
The Gradle build file, as described later in The Build File.
gradlew
andgradlew.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. Since the recommended way to execute any Gradle build is with the help of the Gradle Wrapper,gradlew
is used instead ofgradle
throughout the documentation. However, thegradlew
andgradle
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.
The Build File
At a minimum, the build.gradle
file needs to enable the Vaadin Gradle Plugin:
plugins {
id 'com.vaadin' version '20.0.0' (1)
// Optional
id 'org.gretty' version '3.0.3' (2)
id 'war' (3)
id 'groovy' (4)
}
-
Use the plugin version that matches the Vaadin version. See github.com/vaadin/platform for the latest release. To try the pre-release version of the Vaadin Gradle plugin, see Using plugin pre-release version
-
Use the Gretty embedded web server to run the application during development. See Running the Application for details.
-
Build a WAR package to deploy to a traditional servlet container. You also need to define the Servlet API using
providedCompile "javax.servlet:javax.servlet-api:3.1.0"
in the dependencies section. -
By default, the plugin supports Java. You can include Groovy or Kotlin as an optional plugin.
Vaadin Plugin Configuration
Vaadin Gradle plugin options are configured in a vaadin
block. For development, the block is usually like this:
vaadin {
optimizeBundle = false
}
If the parameter is true
, the front-end bundle is optimized for all supported browsers, but the compilation is much slower. For configuration options, see plugin configuration options
Configuring Repositories
The repositories
section defines the locations to search for packages. The repository that contains the Vaadin libraries is required at a minimum:
repositories {
mavenCentral()
maven { url = "https://maven.vaadin.com/vaadin-addons" }
}
If you want to try the Vaadin platform pre-release versions, you can also add the following repository:
repositories {
maven { url = "https://maven.vaadin.com/vaadin-prereleases" }
}
Note
|
Use Final Release Versions
To avoid any inconsistencies, don’t use pre-release versions in your production environment, especially snapshots. Vaadin recommends using the latest major version. See the https://vaadin.com/releases page for the latest releases.
|
You can use any Gradle repository definitions in the block. See Declaring Repositories in the Gradle documentation for more information.
Configuring Dependencies
You’ll need to add the vaadin-core
or vaadin
library as a Java dependency. You would do that like so:
dependencies {
implementation "com.vaadin:vaadin-core:20.+"
}
When you specify a version of 20.+
, you’re choosing to use the latest version of Vaadin. However, you can also specify the exact version. See Declaring Dependencies in the Gradle documentation for more details.
Compiling
If you’ve defined the default tasks as described earlier in Other Configuration, you can run the following to compile:
./gradlew
On Windows, you would execute instead the following:
gradlew
To avoid unnecessary verbosity, only the Unix style of running ./gradlew
is used for the rest of this document. You’ll need to replace it with gradlew
if you’re using a Windows machine. Otherwise, the project builds with the standard build
task. However, on the first build and also at other times when necessary, you’ll need to build the Vaadin frontend.
./gradlew vaadinBuildFrontend build
Vaadin Tasks
The Vaadin-related tasks handled by the plugin are as follows:
vaadinPrepareFrontend
-
This checks that Node.js and
npm
are installed, copies front-end resources, and creates or updates thepackage.json
and Vite configuration files (i.e.,vite.config.ts
andvite.generated.ts
). The front-end resources are inside.jar
dependencies: they’re copied tonode_modules
. vaadinBuildFrontend
-
This builds the front-end bundle with the
Vite
utility. Vaadin front-end resources (e.g., HTML, JavaScript, CSS, and images) are bundled to optimize loading the frontend. This task isn’t executed automatically on thebuild
and other targets, so you’ll need to run it, explicitly. vaadinClean
-
This cleans the project and removes
node_modules
,package-lock.json
,vite.generated.ts
,tsconfig.json
,types.d.ts
,pnpm-lock.yaml
andpnpmfile.js
. You’ll need to run this task if you upgrade the Vaadin version, and in other similar situations.
To get the complete list of tasks handled by the configured plugins, execute the following:
./gradlew tasks
Incremental Builds
Vaadin uses Gradle Incremental Builds feature for vaadinPrepareFrontend
task to prevent it from running when the project’s configuration hasn’t been changed and the necessary front-end files have already been generated and haven’t changed since the previous build. This saves time when building and running applications in development mode.
If none of these items have been changed since the previous build, Gradle skips the prepare frontend task, giving an UP-TO-DATE
state:
-
Inputs:
-
Installed
Node.js
andnpm/pnpm
versions; and -
Configuration parameters (see plugin configuration options).
-
-
Outputs:
-
package.json
,package-lock.json
,vite.config.js
and other front-end files generated by Vaadin.
-
The incremental build feature can be turned off with the following configuration parameter in the gradle.build
file:
vaadin {
alwaysExecutePrepareFrontend = true
}
This allows you to force the vaadinPrepareFrontend
task execution as a fallback in case of issues in input or output definitions, while it’s being fixed.
Running the Application
You’d use a Spring Boot-based starter (i.e., Vaadin with Spring Boot) to run the application during development in a similar way to any normal Spring Boot application. This means you can run it either from the class containing the main()
method — normally annotated with @SpringBootApplication
— or by using Spring Boot’s Gradle plugin bootRun
task:
./gradlew bootRun
If you’re using a simple web application (i.e., Vaadin without Spring Boot) to run the application during development, the Gradle plugin supports 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.
One way to enable the Gretty plugin is in the plugin
section of the gradle.build
file, as in the starter project:
plugins {
...
id 'org.gretty' version '3.0.3'
}
You can configure Gretty further in an optional gretty
block:
gretty {
contextPath = "/" (1)
servletContainer = "jetty9.4" (2)
}
-
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. -
Use Jetty as the servlet container, with the specified version.
The application is started with the appRun
task:
./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.
You might need to add jcenter()
to the list of repositories to be able to run Gretty tasks. Some artifacts from jcenter()
haven’t yet been moved to mavenCentral()
. In the future, this step becomes unnecessary:
repositories {
// should be removed in the future as jcenter() is obsolete.
jcenter()
}
See the Gretty documentation for a complete reference on using Gretty. For issues when running the application in development mode, see Known Issues for possible solutions.