> Markdown version of [Gradle](https://vaadin.com/docs/next/hilla/reference/gradle). Section index: [llms.txt](https://vaadin.com/docs/next/hilla/llms.txt) # Using Gradle in Vaadin Hilla Applications Maven or Gradle can be used to build and publish Vaadin applications that use Hilla. Most visitors to this documentation, though, tend to use Maven. Therefore, most of the examples, settings, and related instructions on the other documentation pages reference Maven. To use Gradle, you may have to make some adjustments. This particular page, though, describes how to compile, build, and run a Vaadin Hilla application using the Vaadin Gradle plugin — it’s not for Maven developers. When going through the rest of the documentation, you may sometimes want to refer back to this page. For information about the general usage of Gradle, see the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html). > **Note: Learn More About Vaadin Applications** > > This tutorial doesn’t describe Vaadin Hilla application details. It seeks only to explore the Gradle-related parts for brevity. If you’re interested in knowing more about the core concepts of Vaadin applications, see the [Getting Started Guide](https://vaadin.com/docs/next/getting-started.md). > **Note: Hilla Is Now Part Of The Vaadin** > > Hilla is integrated into the Vaadin unified platform. It means that any Vaadin application can use Hilla components and features, so for brevity, "Hilla applications" refers to Vaadin applications that use Hilla. ## Requirements This tutorial is meant for developers with a basic understanding of Java, Spring Boot, and Gradle. Although there’s no need to write or analyze JavaScript, React, HTML, or CSS, understanding their syntax and basic concepts makes it easier to follow. Using Gradle in a Hilla application does not require any extra settings or setup in your development environment than a standard Vaadin project: - [Node.js](https://nodejs.org/) (optional); - JDK 21 or later, for example, [Eclipse Temurin JDK](https://adoptium.net/); - [Gradle](https://gradle.org/install) 8.14 or later (optional). The Vaadin Gradle plugin installs Node.js automatically when running the build for the first time if it’s missing or the installed version is below the minimum required. See [Supported Technologies](https://vaadin.com/docs/next/compatibility.md) for the minimum versions of Node.js and the other technologies Vaadin supports. > **Note: Installing Gradle is optional.** > > You don’t need to install Gradle on your development machine if you’re using the Gradle-based Hilla starter projects, since they include a Gradle Wrapper script. The script downloads and executes Gradle locally for your project. For more information on using the Gradle Wrapper, see the [Official Gradle Documentation](https://docs.gradle.org/current/userguide/gradle_wrapper.html). If you prefer to install Gradle directly, you can find the instructions at You can obtain a Hilla application starter project with Gradle by: 1. Directly download a [ZIP file](https://github.com/vaadin/skeleton-starter-hilla-react-gradle/archive/refs/heads/v25.zip) that contains a minimal hello-world Hilla application. 2. [Spring Initializr](https://start.spring.io/) which enables you to configure a bare-bones Vaadin project by adding the `Vaadin` dependency. Add the Hilla Spring Boot starter to it as described in [Enabling Browser-Callable Services in a Vaadin Project](https://vaadin.com/docs/next/hilla/guides/browser-callable-services.md#enabling). Both starters use React. In a Hilla Lit application, apply the Gradle setup described on this page to your existing project. ## Gradle-Based Project Structure A bare-minimum Gradle-based Hilla application has the following directory layout: ``` [project-root] gradle/ (1) ├── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties src/ ├── main │ ├── frontend/ │ │ ├── themes/ │ │ └── views/ │ │ │ └── helloworld/ │ │ │ └── HelloWorldView.tsx │ │ └── index.html │ ├── java │ └── resources └── test/ build.gradle (2) gradle.properties (3) gradlew (4) gradlew.bat (5) package.json package-lock.json tsconfig.json types.d.ts ``` 1. The directory that contains the Gradle wrapper files. 2. The main Gradle build file. 3. The file that contains properties that are used in the `build.gradle` file. 4. The Gradle wrapper script for Unix based operating systems. 5. The Gradle wrapper script for Microsoft Windows. > **Note: Hilla Lit Applications** > > In a Hilla Lit application, the view is a `HelloWorldView.ts` file, and the `frontend` folder also contains `index.ts` and `routes.ts`. > **Note: Hilla Starter Details May Vary** > > This tutorial only explores the structure of a minimal Hilla application. A starter project also contains other files and folders such as components, layouts, theming, CSS, etc. Those details are not included in this tutorial as they do not affect executing Gradle tasks and commands. Items **1**, **4**, and **5** from the above are not expanded and analyzed in this tutorial because they are standard Gradle Wrapper scripts and related files. If you’re interested in more information about the Gradle Wrapper, see the [Official Gradle Documentation](https://docs.gradle.org/current/userguide/gradle_wrapper.html). ### The `gradle.properties` File Having a `gradle.properties` file is optional for both Gradle and Hilla, but having it can help centralize some configurations and versions in other Gradle-related build files, i.e., the `build.gradle` or `settings.gradle` files. For example, you can set the Vaadin version for your project in the `gradle.properties` file as follows: ```properties vaadinVersion=25.4.0-alpha1 ``` This property is covered in the following sections. ### The `build.gradle` File A minimal `build.gradle` file for a Hilla application looks something like this: ```groovy plugins { id 'java' id 'org.springframework.boot' version '4.1.0' id 'io.spring.dependency-management' version '1.1.7' id 'com.vaadin' version "$vaadinVersion" } repositories { mavenCentral() } dependencies { implementation('com.vaadin:vaadin-spring-boot-starter') implementation('com.vaadin:hilla-spring-boot-starter') developmentOnly('org.springframework.boot:spring-boot-devtools', 'com.vaadin:vaadin-dev') testImplementation 'org.springframework.boot:spring-boot-starter-test' } dependencyManagement { imports { mavenBom "com.vaadin:vaadin-bom:$vaadinVersion" } } ``` Note that the `vaadinVersion` property from `gradle.properties` is resolved automatically. Many useful components and add-ons for Hilla applications are also found in the [Vaadin Directory](https://vaadin.com/directory/), which is why you often see that repository in Hilla starter projects: ```groovy repositories { mavenCentral() maven { setUrl("https://maven.vaadin.com/vaadin-addons") } } ``` > **Note: Pre-Release Versions Require pluginManagement Configuration** > > If you want to try out the Vaadin pre-release versions, add the [Vaadin Pre-releases](https://maven.vaadin.com/vaadin-prereleases) repository. See the [Trying the pre-release versions](#_trying_the_pre_release_versions) section to see how. ### Running the Project Hilla applications rely on Spring Boot for the backend and you can run them like any Spring Boot application. Run the main method of the class annotated with `@SpringBootApplication` in your preferred IDE, or execute the `bootRun` task from the official Spring Boot Gradle plugin: terminal **Windows** ```bash gradlew bootRun ``` terminal **macOS / Linux** ```bash ./gradlew bootRun ``` You can access the running application at . The Vaadin Gradle plugin has tasks that are executed after the compilation and also during the project run. The following section explores the available tasks and their responsibilities. ### Available Hilla Related Tasks in Vaadin Gradle plugin - `hillaConfigure` This task collects configurations from the project and build file. The configuration is required for the TypeScript generation process that comes next. `hillaConfigure` can be executed independently of the startup process as a standard Gradle task: terminal **Windows** ```bash gradlew hillaConfigure ``` terminal **macOS / Linux** ```bash ./gradlew hillaConfigure ``` - `hillaGenerate` This task parses the classes annotated by `@BrowserCallable` to generate an `openapi.json` file. Then the `openapi.json` file is loaded and passed to a process that generates or updates the TypeScript stubs for calling the backend services. `hillaGenerate` can be executed independently of the startup process as a standard Gradle task: terminal **Windows** ```bash gradlew hillaGenerate ``` terminal **macOS / Linux** ```bash ./gradlew hillaGenerate ``` > **Note: Vaadin Gradle plugin Has Other Tasks** > > Note that there are other tasks provided by the Vaadin Gradle plugin such as `vaadinPrepareFrontend` and `vaadinBuildFrontend`, and as they are not Hilla specific tasks that are not covered in this tutorial. For more information, see [Gradle Configuration Properties](https://vaadin.com/docs/next/flow/configuration/gradle.md). ## Plugin Configuration Options The following options are provided by the Vaadin Gradle plugin and can be used while configuring a Vaadin project that uses Hilla. Browser-callable services in a dependency or in another module of a multi-module Gradle project don’t need any configuration in the build file. Hilla finds them among the Spring beans of the application, as described in [Configuration](https://vaadin.com/docs/next/hilla/reference/configuration.md). If the Spring Boot application class is in another module, configure the discovery as described in [Explicit Discovery of Browser-Callable Classes](#_endpoint_discovery). - `productionMode` By default, the Vaadin Gradle plugin builds the project in production package when run with `bootJar` or `bootBuildImage` task. If you plan to build the project for production some other way, configure the `build.gradle` file as follows: Option to be added to the `build.gradle` ```groovy vaadin { productionMode = true } ``` You can find more details about production builds in the [Going to Production](#_production) section. ### Explicit Discovery of Browser-Callable Classes (since V25.2) During code generation, Hilla discovers browser-callable classes — classes annotated with `@BrowserCallable` or `@Endpoint` — automatically. The discovery relies on detecting the Spring Boot application class on the module’s classpath. In some setups, such as multi-module projects where the application class resides in a different module, this auto-detection fails. In these cases, you can configure the discovery explicitly with the following project properties: - `com.vaadin.hilla.mainClass` The fully qualified name of the Spring Boot application class to use for discovering browser-callable classes. The plugin also reads the plain `mainClass` project property as a fallback. - `com.vaadin.hilla.sourceClasses` A comma-separated list of fully qualified names of Spring configuration classes that declare the browser-callable beans. The classes are passed to the Spring Ahead-of-Time (AOT) processor as `--spring.main.sources`, and are used when no Spring Boot application class is found on the classpath. Set the properties in the `gradle.properties` file: ```properties com.vaadin.hilla.mainClass=com.example.application.Application ``` Alternatively, if there is no Spring Boot application class available, list the Spring configuration classes that declare the browser-callable beans: ```properties com.vaadin.hilla.sourceClasses=com.example.application.ApplicationConfiguration,com.example.module.ModuleConfiguration ``` You can also pass the properties on the command line: terminal **Windows** ```bash gradlew -Pcom.vaadin.hilla.mainClass=com.example.application.Application hillaGenerate ``` terminal **macOS / Linux** ```bash ./gradlew -Pcom.vaadin.hilla.mainClass=com.example.application.Application hillaGenerate ``` > **Note:** When either property is set, Hilla discovers browser-callable classes with the Spring AOT-based finder, and skips the default lookup-based auto-detection. ## Going to Production When doing a production-ready build, the Vaadin Gradle plugin transpiles, bundles, and optimizes all the client-side dependencies for a faster startup and better browser performance. `productionMode` can be enabled in three ways: Run `bootJar` task: terminal **Windows** ```bash gradlew bootJar ``` terminal **macOS / Linux** ```bash ./gradlew bootJar ``` In `build.gradle`: ```groovy vaadin { productionMode = true } ``` At the command line: terminal **Windows** ```bash gradlew -Pvaadin.productionMode=true build ``` terminal **macOS / Linux** ```bash ./gradlew -Pvaadin.productionMode=true build ``` > **Note: Spring Boot-Specific Configuration** > > If you are using Vaadin with Spring Boot, the default production packaging is a `jar`. If you want to package the Spring Boot application as a `WAR` instead to be deployed on a standalone container, such as `tomcat`, there are two additional steps: Add the `war` plugin to your `build.gradle` and enable it: Plugin to be added to the `build.gradle` file ```groovy plugins { //…​ other plugins id 'war' } war { enabled = true } ``` Your application class that is annotated with `@SpringBootApplication` extends `SpringBootServletInitializer` and overrides the `configure()` method: Example of Enabling SpringBootServletInitializer ```java @SpringBootApplication public class DemoApplication extends SpringBootServletInitializer { @Override protected SpringApplicationBuilder configure( SpringApplicationBuilder application) { return application.sources(DemoApplication.class); } } ``` Add the following dependency: Dependency to be Added to `build.gradle` ```groovy dependencies { providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat' } ``` When running the Gradle command to create the `WAR` archive, call the `war` task: terminal **Windows** ```bash gradlew -Pvaadin.productionMode=true war ``` terminal **macOS / Linux** ```bash ./gradlew -Pvaadin.productionMode=true war ``` ## Trying the Pre-Release Versions For trying out the Pre-release versions, add the repository and configure it in the following two places: In the `repositories` closure of the `build.gradle` file: ```groovy repositories { mavenCentral() maven { setUrl("https://maven.vaadin.com/vaadin-prereleases") } } ``` In the `build.gradle` file by changing the way you apply the Vaadin Gradle plugin as follows: ```groovy plugins { id 'java' id 'org.springframework.boot' version '4.1.0' id 'io.spring.dependency-management' version '1.1.7' // id 'com.vaadin' version "$vaadinVersion" // should be commented out } apply plugin: 'com.vaadin' // should be added in case of using pre-releases ``` Add `buildscript` to the `settings.gradle` file containing the following: > **Note: \[filename]The settings.gradle file might not exist in your project** > > The `settings.gradle` file is mostly used within multi-module projects, but it’s also useful for other configurations. If you don’t already have it in your project, you can create a plain text file called `settings.gradle` next to your `build.gradle` file, which is in the project root folder. ```groovy buildscript { repositories { gradlePluginPortal() maven { url = 'https://maven.vaadin.com/vaadin-prereleases' } } dependencies { classpath "com.vaadin:vaadin-gradle-plugin:$vaadinVersion" } } ``` You can now try out pre-release and snapshot versions of Vaadin and the Vaadin Gradle plugin. > **Note: Use Final Releases for Production.** > > To avoid any inconsistencies, do not use any pre-release versions, especially snapshots in your production environment. Vaadin always recommends using the latest final release versions. Visit the [Vaadin release](https://github.com/vaadin/platform/releases) page for the latest versions.