Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

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, we use the Gretty Plugin to run it in an embedded web server.

Image
Gradle Plugin Overview

More information about the Vaadin Gradle Plugin is available at the repository at github.com/vaadin/vaadin-gradle-plugin. For information about the general usage of Gradle, please refer to the Gradle User Manual at docs.gradle.org.

Requirements

The Gradle plugin has the following requirements:

  • Windows, Mac, or Linux

  • Java SDK 8 or newer

  • Gradle 5 or 6 (or use provided wrapper from the example projects)

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

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:

https://github.com/vaadin/base-starter-gradle

A minimalistic web application project to be deployed as a WAR package.

$ 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):

Image
Cloned Starter Project

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

The Build File

The build.gradle file needs to at least enable the Vaadin Gradle Plugin:

plugins {
    id 'com.vaadin' version '0.8.0' (1)

    // Optional
    id 'org.gretty' version '3.0.3' (2)
    id 'war' (3)
    id 'groovy' (4)
}

  1. Use the plugin version of your choice.

    Please see the releases at github.com/vaadin/vaadin-gradle-plugin for the latest release.

  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 with the optional plugin.

Vaadin Plugin Configuration

Vaadin Gradle Plugin options are configured in a vaadin block.

Usually, you have it as follows during development:

vaadin {
    optimizeBundle = false
}

If the parameter is set true, the front-end bundle is optimized for all supported browsers, but compilation is much slower.

Other configuration options, with their default values, are as follows:

productionMode = false

Whether the project is compiled for production. For production, the front-end is transpiled for older browsers and optimized, as described in Taking your Application into Production. It is a slow, so it is not normally done during development. Running the vaadinBuildFrontend task will automatically switch this to true, so there is no need for you to configure anything.

See also Going to Production.

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

The plugin will generate additional resource files in the given directory. These files need to be present on the classpath, in order for Vaadin to be able to run, both in the develoment and production mode. The plugin will automatically register it as an additional resource directory, which should then be picked up by the IDE. That allows the application to be deployed, for example, to Tomcat in IntelliJ or Eclipse IDE. For example, the flow-build-info.json goes in the directory. See the webpackOutputDirectory parameter below for more details.

webpackOutputDirectory = File(buildOutputDirectory, "META-INF/VAADIN/")

The folder where webpack should output index.js and other generated files. In the development mode, the flow-build-info.json file is generated here.

npmFolder: File = project.projectDir

The folder where the package.json file is located. The file lists the npm packages and their versions your project depends on. It is by default located at the project root directory.

webpackTemplate: String = "webpack.config.js"

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

webpackGeneratedTemplate = "webpack.generated.js"

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")

The folder where flow will put generated files that will be used by webpack. Should be build/frontend/, but that is only supported in Vaadin 15+.

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

The directory with the frontend source files of the project.

generateBundle = true

Whether to generate a bundle from the project frontend sources or not.

runNpmInstall = true

Whether to run npm install after updating dependencies.

generateEmbeddableWebComponents = true

Whether to generate embeddable web components from WebComponentExporter inheritors.

frontendResourcesDirectory = File(project.projectDir, "src/main/resources/META-INF/resources/frontend")

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

optimizeBundle = true

Whether to use byte code scanner strategy to discover frontend components.

nodeVersion = "12.14.1"

When using the vaadinPrepareNode task, this property specifies which node version to download. Please see the list of all node.js releases. Usually it is best to select the latest LTS release.

Configuring Repositories

The repositories section defines the locations to search for packages. Normally, you need at least the a repository holding Vaadin libraries. They are available at least through jcenter.

repositories {
  jcenter()
}

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 the vaadin-core library as a Java dependency:

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

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

See Declaring dependencies in Gradle documentation for further details.

Other Configuration

In the starter project, we define default targets for convenience, so that you can simply 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 simply do:

$ gradle

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

$ gradle vaadinBuildFrontend build

Vaadin Tasks

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

vaadinBuildFrontend

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

vaadinClean

Cleans the project completely and removes node_modules, package*.json, and webpack.*.js. You need to run this task if you upgrade Vaadin version and in other such situations.

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.

vaadinPrepareNode

Prepares a local node distribution for use by Vaadin. The task requires the optional com.github.node-gradle.node plugin, which you need to specify in the plugins section.

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

$ gradle tasks

Running the Application

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.

See Gretty documentation for a complete reference on using Gretty.

One way to enable the Gretty plugin is in the plugin section of the gradle.build file, as we do in the starter project:

plugins {
  ...
  id 'org.gretty' version '3.0.1'
}

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.

To run the application, simply run the appRun task:

 $ gradle appRun

The task compiles the application and starts the web server in http://localhost:8080/ (assuming that you configured the root context path as described above).

Developing in the Eclipse IDE

Gradle has first-class support at least in the Eclipse IDE, IDEA, NetBeans, and Android Studio. In the following, we go through 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 Eplorer and look like depicted in Cloned Starter Project.

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

Image
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 gretty → appRun 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 Taking your Application into 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:

$ gradle -DproductionMode=true war

330094D2-0538-49A7-BA29-DC83CB5CB6DB