Starting a Project

Gradle is a popular build tool for Java, Groovy, Kotlin, and other projects. It is an alternative to using Maven, and in many ways much more simple to use, while also more powerful if need be. You can use it to build a Vaadin application, run it, and manage dependencies during development.

This tutorial describes how to create, compile, and run a Vaadin application using the Vaadin Gradle Plugin. For running the application, the Gretty Plugin is used to run it in an embedded web server.

For information about the general usage of Gradle, please refer to the Gradle User Manual.

Requirements

To use Vaadin Gradle Plugin, your environment has to meet the following requirements:

  • Windows, Mac, or Linux

  • Java SDK 8 or newer

  • Gradle 5 or 6 (Optional, because of the provided wrapper in the starter projects)

  • Node.js and npm (Optional, because they can also be installed locally to project using the Vaadin Gradle Plugin)

Except for Gradle, these are general Vaadin requirements, as described in Installing Development Tools.

Note
Installing gradle is optional
If you are going to use Vaadin’s Gradle base starter projects, then there is no need to install Gradle on your machine. A Gradle Wrapper script is included in those starter projects which manage download and execution of Gradle locally for your project. For more information on using Gradle Wrapper, please refer to Official Gradle Documentations.

Creating a Vaadin Project

To create a new project, the easiest way is to clone a starter repository containing an application skeleton.

You can also take any existing Vaadin project and make a build.gradle file for it, as described in "The Build File".

Cloning a Starter Repository

The following starter repositories are available at the moment:

Note
Clone the master branch of the starter projects
Please note that the following repositories are default to V14 branch as you clone them. If you intend to use them with the latest version of Vaadin, you must clone the master branch, or simply change to master branch after you cloned either of the starter projects.
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 into javax:javaee-api and potentially adding com.vaadin:vaadin-cdi dependency 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

Once cloned, the project should look as follows (imported in the Eclipse IDE):

Cloned Starter Project
Note
Only the content of simple web application starter is depicted
Note that only the contents of base-starter-gradle (simple web application starter without Spring Boot) is presented in the above figure. Although, there is not much difference in the Spring Boot based starter project, other than having an additional class annotated with @SpringBootApplication. If this is your first time of trying Vaadin with Spring Boot, you may refer to the 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 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 to modify the style of the TextField component.

build.gradle

The Gradle build file as described below in The Build File.

gradlew and gradlew.bat

Gradle wrapper build scripts for Linux/Mac (gradlew) and Windows (gradlew.bat). The build scripts allow building the project without Gradle preinstalled. As the recommended way to execute any Gradle build is with the help of the Gradle Wrapper, we also used gradlew instead of gradle throughout the documentation. Though, gradlew and gradle commands can be used interchangeably if you have Gradle installed already, and you prefer to use your installed Gradle. You can find out more about the benefits of using Gradle Wrapper on the Official Gradle Documentations.

The Build File

The build.gradle file needs to at least 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)
}
  1. Use the plugin version matching the Vaadin version.

    Please see the releases at 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

  2. Use the Gretty embedded web server for running the application during development. See Running the Application for details.

  3. Build a WAR package to deploy to a traditional Servlet container. You also need to define Servlet API using providedCompile "javax.servlet:javax.servlet-api:3.1.0" in the dependencies section.

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

Usually it is as follows during development:

vaadin {
    optimizeBundle = false
}

If the parameter is true, the frontend bundle is optimized for all supported browsers, but compilation is much slower.

For configuration options see plugin configuration options

Configuring Repositories

The repositories section defines the locations to search for packages. At least the repository holding Vaadin libraries is needed:

repositories {
    mavenCentral()
    maven { url = "https://maven.vaadin.com/vaadin-addons" }
}

If you want to try the Vaadin platform pre-release versions you can add the following repository as well:

repositories {
    maven { url = "https://maven.vaadin.com/vaadin-prereleases" }
}
Note
Vaadin recommends to use final releases
To avoid any inconsistencies, do not use any pre-release versions in your production environment, especially snapshots. Vaadin always recommends using the LTS or Final releases of the newer versions. Please visit the Vaadin platform release page for the latest releases of LTS and newer versions' Final releases.

You can use any Gradle repository definitions in the block. See Declaring repositories in Gradle documentation for more information.

Configuring Dependencies

You need to add vaadin-core or vaadin library as a Java dependency:

dependencies {
    implementation "com.vaadin:vaadin-core:20.+"
}

With 20.+ version specification, you choose to use the latest version of Vaadin, but you can also give exact version.

See Declaring dependencies in Gradle documentation for further details.

Other Configuration

In the starter project, default targets are defined for convenience, so that you can run gradle without specifying any tasks:

defaultTasks("clean", "vaadinBuildFrontend", "build")

Compiling

If you defined the default tasks as described above in Other Configuration, you can run:

$ ./gradlew

on Windows:

$ gradlew
Note
Unix style of running gradlew would be used for the rest of this document
To avoid unnecessary verbosity, only Unix Systems style of running ./gradlew is used for the rest of this documentation. Obviously, you must replace it with gradlew if you are on a Windows machine.

Otherwise, the project builds with the standard build task. However, on the first time and also otherwise if it is necessary, you need to build the Vaadin frontend.

$ ./gradlew vaadinBuildFrontend build

Vaadin Tasks

The Vaadin-related tasks handled by the plugin are as follows:

vaadinPrepareFrontend

Checks that node.js and npm are installed, copies frontend resources, and creates or updates package.json and webpack.config.json files. The frontend resources are inside .jar dependencies, and copied to node_modules.

vaadinBuildFrontend

Builds the frontend bundle with the webpack utility. Vaadin frontend resources, such as HTML, JavaScript, CSS, and images, are bundled to optimize loading the frontend. This task is not executed automatically on the build and other targets, so you need to run it explicitly.

vaadinClean

Cleans the project and removes node_modules, package-lock.json, webpack.generated.js, tsconfig.json, types.d.ts, pnpm-lock.yaml and pnpmfile.js. You need to run this task if you upgrade Vaadin version and in other such situations.

To get the complete list of tasks handled by the configured plugins, enter:

$ ./gradlew tasks

Running the Application

If you are using a Spring Boot based starter (Vaadin with Spring Boot), for running the application during development, you would do it similar to any normal Spring Boot application. This means you can either run it from the class containing the main method (which normally annotated with @SpringBootApplication), or by using Spring Boot’s Gradle Plugin bootRun task:

$ ./gradlew bootRun

If you are using simple web application (Vaadin without Spring Boot), for running the application during development, the Gradle plugin supports the Gretty plugin, which runs the application in an embedded web server. You can do that either in an IDE or at command-line as follows:

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)
}
  1. Sets the context path to root path. The default context path contains the project name, so the URL would be http://localhost:8080/myproject (or whatever your project name is).

  2. 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 above).

Note that you might need to add jcenter() to the list of repositories to be able to run Gretty’s tasks, depending on when you are following this documentation. Currently, still some artifacts from jcenter() haven’t been moved to mavenCentral(), so this would be an unnecessary step in the future:

repositories {
    // should be removed in the future as jcenter() is obsolete.
    jcenter()
}

See Gretty documentation for a complete reference on using Gretty.

Developing in the Eclipse IDE

Gradle has first-class support at least in the Eclipse IDE, IDEA, NetBeans, and Android Studio. The following part explores how to create, import, and develop a Vaadin Gradle project in the Eclipse IDE.

Importing a New Project

You create a new Vaadin project either by cloning the repository on command-line and importing it to Eclipse as a Gradle project.

  1. Clone the starter repository of you choice as described earlier.

  2. Select File  Import  Gradle  Existing Gradle Project.

  3. Enter or select the Project root directory.

  4. Click Finish.

The project should appear in the Project Explorer and look like depicted in Cloned Starter Project.

You should now see the Gradle Tasks tab; you can browse all the various available tasks.

Gradle Tasks tab in Eclipse

Running the Application

You can run the project using Gretty in an embedded web server.

  1. Open the Gradle Tasks tab

  2. Double-click the grettyappRun task

    • The Gradle Executions tab opens and shows build progress

  3. When the :apprun task is running, open the browser at http://localhost:8080.

  4. To stop the server go to the Console tab and press any key.

Going to Production

To build a web application as a WAR package, you need the war plugin. You also need to enable it.

In build.gradle, you need to include the plugin and enable WAR build:

plugins {
  ...
  id 'war'
}

war {
    enabled = true
}

When making a production-ready build, the Vaadin Gradle Plugin transpiles the client-side dependencies to legacy browsers, as described in Deploying to Production. You enable that by either setting it in build.gradle or at command-line when invoking Gradle.

In build.gradle:

vaadin {
   productionMode = true
}

At command-line:

$ ./gradlew -Pvaadin.productionMode=true war
Note
Spring Boot specific configurations
If you are using Vaadin with Spring Boot, normally the default packaging for production would be the jar. But, if you intend to package a Spring Boot application as WAR to be deployed on a standalone container such as tomcat, there are two additional steps needed to take:
  • Your application class that is annotated with @SpringBootApplication should extend SpringBootServletInitializer and override the configure method:

@SpringBootApplication
public class DemoApplication extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(
	                     SpringApplicationBuilder application) {
        return application.sources(DemoApplication.class);
    }
}
  • Adding the following dependency:

dependencies {
    providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
}

Using Gradle Plugin Snapshot Versions

A snapshot version of the plugin is pushed to the pre-release repository. Note that this section is about trying the pre-release and snapshot versions of the Vaadin Gradle Plugin itself, not the Vaadin platform.

To use the pre-released plugin add the vaadin-prereleases repository to the project settings.gradle file. settings.gradle is mostly used within multi-module projects, but it comes handy for other configurations as well. Thus, if you don’t have it already in your project, go ahead and create a plain text file called settings.gradle next to your build.gradle file (normally in project root folder).

pluginManagement {
    repositories {
        maven { url = 'https://maven.vaadin.com/vaadin-prereleases' }
        gradlePluginPortal()
    }
}

Then the plugin needs to be defined and applied in the build.gradle file.

buildscript {
    ...
    dependencies {
        classpath group: 'com.vaadin',
                name: 'vaadin-gradle-plugin',
                version: '20.0-SNAPSHOT'
    }
}

plugins {
    ...
}

apply plugin: 'com.vaadin'
Note
Remember to update the plugins block
Note that id 'com.vaadin' version 'xyz' should also be removed from the plugins block, and only apply plugin: 'com.vaadin' is applying the plugin (as demonstrated in the above).

Plugin Configuration Options

In this list are all configuration options with their default values:

productionMode: Boolean = false

Define if application is running in productionMode. Defaults to false. For production, the frontend is transpiled for older browsers and optimized, as described in Deploying to Production. Running the vaadinBuildFrontend task automatically switches this to true, so there is no need to configure anything.

webpackOutputDirectory: File? = null

The folder where webpack should output index.js and other generated files. Defaults to null which uses the automatically detected value of the main SourceSet, usually build/resources/main/META-INF/VAADIN/webapp/.

npmFolder: File = project.projectDir

The folder where package.json file is located. Default is project root dir.

webpackTemplate: String = FrontendUtils.WEBPACK_CONFIG

Copy the webapp.config.js from the specified URL if missing. Default is the template provided by this plugin. Set it to empty string to disable the feature.

webpackGeneratedTemplate: String = FrontendUtils.WEBPACK_GENERATED

Copy the webapp.generated.js from the specified URL. Default is the template provided by this plugin. Set it to empty string to disable the feature.

generatedFolder: File(project.projectDir, "target/frontend")

Target folder for generated files used by webpack.

frontendDirectory: File(project.projectDir, "frontend")

The directory with the frontend source files of the project.

generateBundle: Boolean = true

Generate a bundle from the project frontend sources if true.

runNpmInstall: Boolean = true

Run npm install after updating dependencies.

generateEmbeddableWebComponents: Boolean = true

Generate web components from WebComponentExporter inheritors.

frontendResourcesDirectory: File = File(project.projectDir, Constants.LOCAL_FRONTEND_RESOURCES_PATH)

Defines the project frontend directory from where resources should be copied from for use with webpack.

optimizeBundle: Boolean = true

Use byte code scanner strategy to discover frontend components.

pnpmEnable: Boolean = true

Instructs to use pnpm for installing npm frontend resources. Default is true

requireHomeNodeExec: Boolean = false

Whether vaadin home node executable usage is forced. If it’s set to true then vaadin home 'node' is checked and installed if absent. This is then be used instead of globally or locally installed 'node'.

useDeprecatedV14Bootstrapping: Boolean = false

Defines if the application should run in legacy V14 bootstrap mode. Defaults to false.

eagerServerLoad: Boolean = false

Define if the initial UIDL object is added to the bootstrap index.html. Defaults to false.

applicationProperties: File = File(project.projectDir, "src/main/resources/application.properties")

Application properties file in Spring project.

openApiJsonFile: File = File(project.buildDir, "generated-resources/openapi.json")

Generated path of the OpenAPI JSON.

javaSourceFolder: File = File(project.projectDir, "src/main/java")

Java source folders for connect scanning.

generatedTsFolder: File = File(project.projectDir, "frontend/generated")

Folder where Flow puts TS API files for client projects.

nodeVersion: String = "v14.15.4"

The node.js version to be used when node.js is installed automatically by Vaadin, for example "v14.15.4". Defaults to [FrontendTools.DEFAULT_NODE_VERSION].

nodeDownloadRoot: String = "https://nodejs.org/dist/"

URL to download node.js from. This can be needed in corporate environments where the node.js download is provided from an intranet mirror. Defaults to [NodeInstaller.DEFAULT_NODEJS_DOWNLOAD_ROOT].

resourceOutputDirectory: File = File(project.buildDir, "vaadin-generated")

Define the output directory for generated non-served resources, such as the token file. Defaults to build/vaadin-generated folder.