Docs

Docs

Gradle Configuration Properties

Configuring the Vaadin Gradle plugin.

This page describes how to configure a Vaadin application using the Vaadin Gradle plugin.

See Alternatives - Gradle page for a guide on creating a Vaadin project with Gradle.

For information about using Gradle, see the Gradle User Manual.

Note
Requirements
The Vaadin Gradle plugin requires Java SDK 17 or later, Gradle 8.7 or later. It 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.

Vaadin Plugin Configuration

Vaadin Gradle plugin options are configured in a vaadin block. An example configuration could be like this:

Source code
vaadin {
    frontendHotdeploy = true
}

If the parameter is true, it enables development using the frontend development server instead of an application bundle. This applies only to development mode.

Configuring Repositories

The repositories section defines the locations to search for packages. The repository that contains the Vaadin libraries is required at a minimum.

Source code
repositories {
    mavenLocal()
    mavenCentral()
    maven { url = "https://maven.vaadin.com/vaadin-addons" }
    maven { url "https://maven.vaadin.com/vaadin-prereleases" }
    maven { url "https://plugins.gradle.org/m2/" }
}

The example above shows configured repositories in the following order:

  • Maven local - Repository which looks in the local Maven cache for dependencies.

  • Maven central (required) - contains Vaadin and a lot of other public libraries

  • repository for Vaadin add-ons

  • repository for Vaadin pre-releases - not recommended for production environments

  • Gradle plugin repository - only necessary when using Gradle community plugins, which are not available through Maven central

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:

Source code
dependencies {
    implementation "com.vaadin:vaadin-core:24.9.3"
}

Vaadin Tasks

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

vaadinPrepareFrontend

This step verifies that Node.js and npm are installed, copies the frontend resources, and, if needed, creates or updates the package.json file and Vite configuration files (i.e., vite.config.ts and vite.generated.ts). The frontend resources are located within .jar dependencies and are copied to src/main/frontend/generated/jar-resources.

vaadinBuildFrontend

This builds the frontend bundle with the Vite utility. Vaadin frontend resources (e.g., HTML, JavaScript, CSS, and images) are bundled to optimize loading the frontend. This task isn’t executed automatically on the build 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 and pnpmfile.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:

Source code
terminal
./gradlew tasks

(gradlew tasks on Windows)

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

Outputs

  • package.json, package-lock.json, vite.config.js and other frontend files generated by Vaadin.

The incremental build feature can be turned off with the following configuration parameter in the gradle.build file:

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

Production

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

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

Source code
plugins {
  ...
  id 'war'
}

war {
    enabled = true
}

When doing a production-ready build, the Vaadin Gradle plugin bundles and optimizes the client-side dependencies, as described in Deploying to Production. You enable this by either setting it in build.gradle or at the command line when invoking Gradle.

In build.gradle:

Source code
Enabling Vaadin Production Mode through the build.gradle file
vaadin {
   productionMode = true
}

At the command-line, execute the following:

Source code
Enable Vaadin Production Mode from Command-Line
./gradlew -Pvaadin.productionMode=true war

(or gradlew -Pvaadin.productionMode=true war on Windows)

If you’re using Vaadin with Spring Boot, the default packaging for production would normally be the jar. However, if you intend to package a Spring Boot application as a WAR to be deployed on a standalone container (e.g., tomcat), there are two additional steps you’ll need to perform.

First, your application class that’s annotated with @SpringBootApplication should extend SpringBootServletInitializer and override the configure() method:

Source code
Enabling SpringBootServletInitializer example
@SpringBootApplication
public class DemoApplication extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(
	                     SpringApplicationBuilder application) {
        return application.sources(DemoApplication.class);
    }
}

Second, add the following dependency:

Source code
The build.gradle file dependency
dependencies {
    providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat'
}

Using Gradle plugin Snapshot Versions

To use the pre-release version of the Vaadin Gradle plugin, add the vaadin-prereleases repository to the project settings.gradle file. This file is mostly used within multi-module projects, but it’s useful for other configurations. Thus, if you don’t already have it in your project, create a plain text file called settings.gradle next to your build.gradle file, which is normally in the project root folder.

Source code
Plugin repository in the settings.gradle file
pluginManagement {
  repositories {
      maven { url = 'https://maven.vaadin.com/vaadin-prereleases' }
      gradlePluginPortal()
  }
  plugins {
      id 'com.vaadin' version "24.9-SNAPSHOT"
  }
}

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

Source code
Define the snapshot plugin
plugins {
    ...
	id 'com.vaadin'
}
Note
Use Stable Release Versions
To avoid any inconsistencies, don’t use pre-release versions in your production environment, especially snapshots. Vaadin recommends using the latest stable version.

Plugin Configuration Options

Here are all of the configuration options with their default values:

productionMode: Boolean = false

Indicates that the application is running in production mode. Defaults to false. For production, the frontend is bundled and optimized, as described in Deploying to Production. Running the vaadinBuildFrontend task automatically switches this to true, so there’s no need to configure anything.

forceProductionBuild: Boolean = false

Whether to generate a production bundle even if an existing pre-compiled bundle could be used. A value of 'true' forces bundle generation without validating if there is a usable production bundle already.

frontendOutputDirectory: File = null

The folder where Vite 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 the package.json file is located. Defaults to the project root directory.

frontendDirectory: File(project.projectDir, "src/main/frontend")

The directory with the frontend source files of the project. The legacy location "${project.basedir}/frontend" is used if the default location doesn’t exist and this parameter isn’t set.

generateBundle: Boolean = true

Set to true to generate a bundle from the project frontend sources.

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)

Identifies the project frontend directory from where resources should be copied for use with Vite.

optimizeBundle: Boolean = true

Use byte code scanner strategy to discover frontend components.

pnpmEnable: Boolean = false

Use pnpm for installing npm frontend resources. Defaults to false.

useGlobalPnpm: Boolean = false

Use the globally installed pnpm tool or the default supported pnpm version. Defaults to false.

bunEnable: Boolean = false

Use bun for installing npm frontend resources. Defaults to false.

requireHomeNodeExec: Boolean = false

Force use of Vaadin home node executable. If it’s set to true, Vaadin home node is checked, and installed if absent. This is then be used instead of the globally or locally installed node.

useDeprecatedV14Bootstrapping: Boolean = false

Run the application in legacy V14 bootstrap mode. Defaults to false.

eagerServerLoad: Boolean = false

Add the initial User Interface Definition Language (UIDL) object to the bootstrap index.html. Defaults to false.

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

Application properties file in a 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, "src/main/frontend/generated")

The folder where Flow puts TS API files for client projects. The legacy location "${project.basedir}/frontend/generated" is used if the default location doesn’t exist and this parameter isn’t set.

nodeVersion: String = "v18.17.1"

The Node.js version to be used when Node.js is installed automatically by Vaadin, for example "v18.17.1". 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].

nodeAutoUpdate: Boolean = false

Flag to enable automatic update of the Node.js version installed in ~/.vaadin, if it’s older than the default or defined nodeVersion.

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

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

reactEnable: Boolean = true

Whether to use React Router, add React core dependencies, React integration helpers and Vaadin’s provided React components (@vaadin/react-components). Fallbacks to vaadin-router, excludes all React dependencies and adds Lit dependencies, if set to false.

filterClasspath: Action<ClasspathFilter>

Use the include and exclude functions to specify the scanned classpath. Supports glob patterns, e.g., include("com.vaadin:*") (all artifacts under the com.vaadin group).

Known Issues

When the list of dependencies causes the classpath to go over a set limit on Windows, the build automatically generates a JAR containing a manifest with the classpath. Sometimes, when running a Spring Boot application, the resource loader doesn’t load the classpath packages correctly from the manifest. The failed annotation scanning makes the required npm packages unavailable.

You can fix this in two ways: add the repository mavenLocal() to build file repositories; or specify the vaadin.allowed-packages property, see Vaadin Spring Configuration.