From fcdc1c69e191311ef50b72605ac4dde48e268400 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petter=20Holmstr=C3=B6m?= Date: Sat, 10 Oct 2026 11:18:26 +0300 Subject: [PATCH] docs: update Hilla Gradle reference for Vaadin 25 Correct the stale facts on the Hilla Gradle reference page: the requirements, the starter ZIP branch, the plugin versions in the build file examples, the build file name in the project tree, and the Hilla plugin options and tasks that changed when the Hilla Gradle plugin was merged into the Vaadin Gradle plugin. Co-Authored-By: Claude Opus 5.5 --- articles/hilla/reference/gradle.adoc | 63 ++++++++++++---------------- 1 file changed, 26 insertions(+), 37 deletions(-) diff --git a/articles/hilla/reference/gradle.adoc b/articles/hilla/reference/gradle.adoc index 802c095fe0..c67ad36ae2 100644 --- a/articles/hilla/reference/gradle.adoc +++ b/articles/hilla/reference/gradle.adoc @@ -5,6 +5,8 @@ description: Building and running a Hilla application using Gradle. meta-description: Integrate Vaadin Hilla applications with Gradle for streamlined build processes. --- +include::{articles}/_vaadin-version.adoc[] + = Using Gradle in Vaadin Hilla Applications [.introText] @@ -29,11 +31,13 @@ This tutorial is meant for developers with a basic understanding of Java, Spring Using Gradle in a Hilla application does not require any extra settings or setup in your development environment than a standard Vaadin project: // tag::requirements[] -- https://nodejs.org/[Node] 18; -- JDK 17 or later, for example, https://adoptium.net/[Eclipse Temurin JDK]; -- https://gradle.org/install[Gradle] (optional). +- https://nodejs.org/[Node.js] (optional); +- JDK 21 or later, for example, https://adoptium.net/[Eclipse Temurin JDK]; +- https://gradle.org/install[Gradle] 8.14 or later (optional). // end::requirements[] +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 <<{articles}/compatibility#,Supported Technologies>> for the minimum versions of Node.js and the other technologies Vaadin supports. + .Installing Gradle is optional. [NOTE] 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 https://docs.gradle.org/current/userguide/gradle_wrapper.html[Official Gradle Documentation]. If you prefer to install Gradle directly, you can find the instructions at https://gradle.org/install @@ -44,7 +48,7 @@ You can obtain a Hilla application starter project with Gradle by: . Directly download a -https://github.com/vaadin/skeleton-starter-hilla-react-gradle/archive/refs/heads/v24.zip[ZIP file] +https://github.com/vaadin/skeleton-starter-hilla-react-gradle/archive/refs/heads/v25.zip[ZIP file] that contains a minimal hello-world Hilla application. . https://start.spring.io/[Spring Initializr] 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 <<../guides/browser-callable-services#enabling, Enabling Browser-Callable Services in a Vaadin Project>>. @@ -74,7 +78,7 @@ src/ │ ├── java │ └── resources └── test/ -gradle.build <2> +build.gradle <2> gradle.properties <3> gradlew <4> gradlew.bat <5> @@ -104,11 +108,11 @@ Items *1*, *4*, and *5* from the above are not expanded and analyzed in this tut Having a [filename]`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 [filename]`build.gradle` or [filename]`settings.gradle` files. -For example, you can set the Hilla version for your project in the [filename]`gradle.properties` file as follows: +For example, you can set the Vaadin version for your project in the [filename]`gradle.properties` file as follows: [source,properties,subs="normal"] ---- -vaadinVersion=25.0.0 +vaadinVersion={vaadin-version} ---- This property is covered in the following sections. @@ -121,8 +125,8 @@ A minimal [filename]`build.gradle` file for a Hilla application looks something ---- plugins { id 'java' - id 'org.springframework.boot' version '3.0.6' - id 'io.spring.dependency-management' version '1.1.0' + id 'org.springframework.boot' version '{spring-boot-version}' + id 'io.spring.dependency-management' version '1.1.7' id 'com.vaadin' version "$vaadinVersion" } @@ -131,11 +135,9 @@ repositories { } dependencies { - implementation('com.vaadin:vaadin-spring-boot-starter') { - exclude group: 'com.vaadin', module: 'vaadin-dev' - } + 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') + developmentOnly('org.springframework.boot:spring-boot-devtools', 'com.vaadin:vaadin-dev') testImplementation 'org.springframework.boot:spring-boot-starter-test' } @@ -163,7 +165,7 @@ repositories { .Pre-Release Versions Require `pluginManagement` Configuration [NOTE] -If you want to try out the Hilla pre-release versions, add the https://maven.vaadin.com/vaadin-prereleases[Vaadin Pre-releases] repository. See the <<#_trying_the_pre_release_versions,Trying the pre-release versions>> section to see how. +If you want to try out the Vaadin pre-release versions, add the https://maven.vaadin.com/vaadin-prereleases[Vaadin Pre-releases] repository. See the <<#_trying_the_pre_release_versions,Trying the pre-release versions>> section to see how. [#_run] @@ -197,7 +199,7 @@ The Vaadin Gradle plugin has tasks that are executed after the compilation and a === Available Hilla Related Tasks in Vaadin Gradle plugin `hillaConfigure`:: - This task collects configurations from the project and build file and creates a temporary file in the [filename]`build` directory with the name, [filename]`hilla-engine-configuration.json`. This file is required for the TypeScript generation process that comes next. `hillaConfigure` can be executed independently of the startup process as a standard Gradle task: + 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: [.example] -- @@ -217,7 +219,7 @@ gradlew hillaConfigure -- `hillaGenerate`:: - This task reads the configuration file created by the configure task, and then parses the classes annotated by [annotationname]`@BrowserCallable` to generate an [filename]`openapi.json` file. Then the [filename]`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: + This task parses the classes annotated by [annotationname]`@BrowserCallable` to generate an [filename]`openapi.json` file. Then the [filename]`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: [.example] -- @@ -236,29 +238,16 @@ gradlew hillaGenerate ---- -- -.Vaadin Gradle Plugin Has Other Tasks +.Vaadin Gradle plugin Has Other Tasks [NOTE] -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, please see <<{articles}/getting-started/starters/gradle#, Starting a Vaadin Project with Gradle>>. +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 <<{articles}/flow/configuration/gradle#, Gradle Configuration Properties>>. [#_all_options] == Plugin Configuration Options -The following options are provided by the Hilla Gradle plugin and can be used while configuring a Vaadin project: - -`exposedPackagesToParser`:: - By default, the classes annotated by [annotationname]`@BrowserCallable` in the [filename]`src` of the current Gradle module are parsed by Hilla to generate TypeScript code for calling the services. If you have browser-callable services 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: - -.Option to be Added to [filename]`build.gradle` -[source,groovy,subs="normal"] ----- -hilla { - exposedPackagesToParser = ["com.example.application", "org.another.example.foobar"] -} ----- +The following options are provided by the Vaadin Gradle plugin and can be used while configuring a Vaadin project that uses Hilla. -.Exposing Services from Current Module or Project -[NOTE] -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. +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 <>. If the Spring Boot application class is in another module, configure the discovery as described in <<#_endpoint_discovery, Explicit Discovery of Browser-Callable Classes>>. `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 [filename]`build.gradle` file as follows: @@ -284,7 +273,7 @@ In these cases, you can configure the discovery explicitly with the following pr 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 AOT processor as `--spring.main.sources`, and are used when no Spring Boot application class is found on the classpath. + 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 [filename]`gradle.properties` file: @@ -459,14 +448,14 @@ repositories { } ---- -In the [filename]`build.gradle` file by changing the way you apply the Hilla Gradle plugin as follows: +In the [filename]`build.gradle` file by changing the way you apply the Vaadin Gradle plugin as follows: [source,groovy,subs="normal"] ---- plugins { id 'java' - id 'org.springframework.boot' version '3.0.6' - id 'io.spring.dependency-management' version '1.1.0' + id 'org.springframework.boot' version '{spring-boot-version}' + id 'io.spring.dependency-management' version '1.1.7' // id 'com.vaadin' version "$vaadinVersion" // should be commented out }