Documentation

Documentation

Using Gradle in Hilla Applications

Building and running Hilla applications with Gradle.

Maven or Gradle can be used to build and publish Hilla applications. 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 Hilla application using the Hilla 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.

Note
Learn More About Hilla Applications
This tutorial doesn’t describe 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 Hilla applications, see the Getting Started Tutorial.

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, 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 Hilla project:

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. If you prefer to install Gradle directly, you can find the instructions at https://gradle.org/install

You can obtain a Hilla starter project with Gradle by:

  1. Directly download a ZIP file that contains a minimal hello-world Hilla application.

  2. Spring Initializr which enables you to configure a bare-bones Hilla project by adding the Hilla dependency.

Gradle-Based Hilla Project Structure

A bare-minimum Gradle-based Hilla application has the following directory layout:

[project-root]
frontend/
└── views/
    └── helloworld/
        └── HelloWorldView.ts
└── index.html
└── index.ts
└── routes.ts
gradle/                             (1)
└── wrapper
    ├── gradle-wrapper.jar
    └── gradle-wrapper.properties
src/
└── main
    ├── java
    └── resources
└── test/
gradle.build                        (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 Starter Details May Vary
This tutorial only explores the structure of a minimal Hilla application. If you download a starter project, for example, from the official repository mentioned above in Requirements, it 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.

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 Hilla version for your project in the gradle.properties file as follows:

hillaVersion=2.1.0

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:

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.0.6'
    id 'io.spring.dependency-management' version '1.1.0'
    id 'com.vaadin.hilla' version "$hillaVersion"
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.vaadin.hilla:hilla-spring-boot-starter'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

dependencyManagement {
    imports {
        mavenBom "com.vaadin.hilla:hilla-bom:$hillaVersion"
    }
}

Note that the hillaVersion property from gradle.properties is resolved automatically.

Many useful components and add-ons for Hilla applications are also found in the Vaadin Directory, which is why you often see that repository in Hilla starter projects:

repositories {
    mavenCentral()
    maven {
        setUrl("https://maven.vaadin.com/vaadin-addons")
    }
}
Note
Pre-Release Versions Require pluginManagement Configuration
If you want to try out the Hilla pre-release versions, add the Vaadin Pre-releases repository. See the 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:

gradlew bootRun

You can access the running application at http://localhost:8080.

The Hilla 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 Tasks in Hilla Gradle Plugin

hillaConfigure

This task collects configurations from the project and build file and creates a temporary file in the build directory with the name, hilla-engine-configuration.json. This file is required for the endpoint generation process that comes next. hillaConfigure can be executed independently of the startup process as a standard Gradle task:

gradlew hillaConfigure
hillaGenerate

This task reads the configuration file created by the configure task, and then parses the classes annotated by @Endpoint 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 backend endpoints. hillaGenerate can be executed independently of the startup process as a standard Gradle task:

gradlew hillaGenerate

hillaInitApp

This task is not related to running a Hilla application and is therefore not mandatory. If you obtain a bare-bones Hilla project, for example, from Spring Initializr, it has no routes, no views, no endpoints, etc., and may therefore be a confusing starting point. This task scaffolds a sample Hello-World endpoint and view, and also required frontend dependencies and TypeScript configurations to boost development. hillaInitApp can be executed as a standard Gradle task, like this:

gradlew hillaInitApp

Plugin Configuration Options

The following options are provided by the Hilla Gradle Plugin and can be used while configuring a Hilla project:

exposedPackagesToParser

By default, the classes annotated by @Endpoint in the src of the current Gradle module are parsed by Hilla to generate TypeScript code for calling the endpoints. If you have Hilla Endpoints in a dependency or in another module of a multi-module Gradle project, you need to explicitly expose their package to Hilla. You can achieve this like so:

hilla {
    exposedPackagesToParser = ["com.example.application", "org.another.example.foobar"]
}
Note
Exposing Endpoints from Current Module or Project
If you expose any package from dependencies (or other modules in a multi-module project), you also need to expose the packages of your current module as well. Hilla misses the sources of the current module or project, unless you explicitly expose them.
productionMode

By default, the hilla-gradle-plugin assumes that the project is going to be built and run in development mode. If you plan to build the project for production, configure the build.gradle file as follows:

hilla {
   productionMode = true
}

You can find more details about production builds in the Going to Production section.

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 two ways:

In build.gradle:

hilla {
   productionMode = true
}

At the command line:

gradlew -Philla.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:

plugins {
  //…​ other plugins
  id 'war'
}

war {
    enabled = true
}

Your application class that is annotated with @SpringBootApplication extends SpringBootServletInitializer and overrides the configure() method:

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

Add the following dependency:

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

When running the Gradle command to create the WAR archive, call the war task:

gradlew -Pvaadin.productionMode=true war

Trying the Pre-Release Versions

For trying out the Pre-release versions, add the https://maven.vaadin.com/vaadin-prereleases repository and configure it in the following two places:

In the repositories closure of the build.gradle file:

repositories {
    mavenCentral()
    maven {
        setUrl("https://maven.vaadin.com/vaadin-prereleases")
    }
}

In the build.gradle file by changing the way you apply the Hilla Gradle Plugin as follows:

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.0.6'
	id 'io.spring.dependency-management' version '1.1.0'
	//id 'com.vaadin.hilla' version "$hillaVersion"
}

apply plugin: 'dev.hilla' // this is how it works 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. 
buildscript {
    repositories {
        gradlePluginPortal()
        maven { url = 'https://maven.vaadin.com/vaadin-prereleases' }
    }
    dependencies {
        classpath "dev.hilla:hilla-gradle-plugin:$hillaVersion"
    }
}

You can now try out pre-release and snapshot versions of Hilla and the Hilla 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 platform release page for the latest versions.