Skip to content

Commit

Permalink
fix: fix outdated information on Hilla Gradle article (#3718)
Browse files Browse the repository at this point in the history 
* fix: fix outdated information

* fix lint errors

* fix lint errors
  • Loading branch information
@taefi
taefi committed Sep 26, 2024
1 parent e2e4ce1 commit 4acb3e7
Showing 1 changed file with 49 additions and 99 deletions.
148 changes: 49 additions & 99 deletions articles/hilla/lit/reference/gradle.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,21 @@ description: Building and running Hilla applications with Gradle.
:hilla-lit:
// tag::content[]

= [since:dev.hilla:hilla@v2.1]#Using Gradle in Hilla Applications#
= [since:dev.hilla:hilla@v2.1]#Using Gradle in Vaadin Hilla Applications#

[.introText]
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.
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 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 link:https://docs.gradle.org/current/userguide/userguide.html[Gradle User Manual].
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 link:https://docs.gradle.org/current/userguide/userguide.html[Gradle User Manual].

.Learn More About Hilla Applications
.Learn More About Vaadin Applications
[NOTE]
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
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/tutorial#, Getting Started Tutorial>>.

.Hilla Is Now Part Of The Vaadin
[NOTE]
As of Vaadin 24.4, 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]
== Requirements
Expand All @@ -42,15 +45,15 @@ You don't need to install Gradle on your development machine if you're using the

pass:[<!-- vale Vale.Spelling = NO -->]

You can obtain a Hilla starter project with Gradle by:
You can obtain a Hilla application starter project with Gradle by:


. Directly download a
ifdef::hilla-react[]
https://github.com/vaadin/skeleton-starter-hilla-react-gradle/archive/refs/heads/main.zip[ZIP file]
https://github.com/vaadin/skeleton-starter-hilla-react-gradle/archive/refs/heads/v24.zip[ZIP file]
endif::hilla-react[]
ifdef::hilla-lit[]
https://github.com/vaadin/skeleton-starter-hilla-lit-gradle/archive/refs/heads/v2.zip[ZIP file]
https://github.com/vaadin/skeleton-starter-hilla-lit-gradle/archive/refs/heads/v24.zip[ZIP file]
endif::hilla-lit[]
that contains a minimal hello-world Hilla application.
. https://start.spring.io/[Spring Initializr] which enables you to configure a bare-bones Hilla project by adding the `Hilla` dependency.
Expand All @@ -64,34 +67,32 @@ A bare-minimum Gradle-based Hilla application has the following directory layout

----
[project-root]
frontend/
└── views/
└── helloworld/
gradle/ <1>
├── wrapper
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
src/
├── main
│ ├── frontend/
│ │ ├── themes/
│ │ └── views/
│ │ │ └── helloworld/
ifdef::hilla-react[]
└── HelloWorldView.tsx
│ │ │ └── HelloWorldView.tsx
endif::hilla-react[]
ifdef::hilla-lit[]
└── HelloWorldView.ts
│ │ │ └── HelloWorldView.ts
endif::hilla-lit[]
ifdef::hilla-react[]
└── App.tsx
└── index.html
└── index.ts
└── routes.tsx
│ │ └── index.html
endif::hilla-react[]
ifdef::hilla-lit[]
└── index.html
└── index.ts
└── routes.ts
│ │ └── index.html
│ │ └── index.ts
│ │ └── routes.ts
endif::hilla-lit[]
gradle/ <1>
└── wrapper
├── gradle-wrapper.jar
└── gradle-wrapper.properties
src/
└── main
├── java
└── resources
│ ├── java
│ └── resources
└── test/
gradle.build <2>
gradle.properties <3>
Expand Down Expand Up @@ -123,7 +124,7 @@ For example, you can set the Hilla version for your project in the [filename]`gr

[source,properties,subs="normal"]
----
hillaVersion=2.1.0
vaadinVersion=24.4.0
----

This property is covered in the following sections.
Expand All @@ -132,62 +133,33 @@ This property is covered in the following sections.

A minimal [filename]`build.gradle` file for a Hilla application looks something like this:

ifdef::hilla-react[]
[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 'com.vaadin.hilla' version "$hillaVersion"
}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.vaadin.hilla:hilla-react-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"
}
}
----
endif::hilla-react[]

ifdef::hilla-lit[]
----
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"
id 'com.vaadin' version "$vaadinVersion"
}
repositories {
mavenCentral()
}
dependencies {
implementation 'com.vaadin.hilla:hilla-spring-boot-starter'
implementation 'com.vaadin:vaadin-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"
mavenBom "com.vaadin:vaadin-bom:$vaadinVersion"
}
}
----
endif::hilla-lit[]

Note that the `hillaVersion` property from [filename]`gradle.properties` is resolved automatically.
Note that the `vaadinVersion` property from [filename]`gradle.properties` is resolved automatically.

Many useful components and add-ons for Hilla applications are also found in the https://vaadin.com/directory/[Vaadin Directory], which is why you often see that repository in Hilla starter projects:

Expand Down Expand Up @@ -231,11 +203,11 @@ 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.
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_gradle_tasks]
=== Available Tasks in Hilla Gradle Plugin
=== 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 endpoint generation process that comes next. `hillaConfigure` can be executed independently of the startup process as a standard Gradle task:
Expand Down Expand Up @@ -277,36 +249,14 @@ gradlew hillaGenerate
----
--

pass:[<!-- vale Vale.Spelling = NO -->]

`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 https://start.spring.io/[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:

[.example]
--
.terminal
[source,bash,subs="+attributes"]
----
<source-info group="Windows"></source-info>
gradlew hillaInitApp
----

.terminal
[source,bash,subs="+attributes"]
----
<source-info group="macOS / Linux"></source-info>
./gradlew hillaInitApp
----
--

pass:[<!-- vale Vale.Spelling = YES -->]

.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 <</getting-started/project/gradle.adoc#, Starting a Vaadin Project with Gradle>>.

[#_all_options]
== Plugin Configuration Options

The following options are provided by the Hilla Gradle Plugin and can be used while configuring a Hilla project:
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 [annotationname]`@Endpoint` in the [filename]`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:
Expand All @@ -324,12 +274,12 @@ hilla {
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 [filename]`build.gradle` file as follows:
By default, the Vaadin 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 [filename]`build.gradle` file as follows:

.Option to be added to the [filename]`build.gradle`
[source,groovy,subs="normal"]
----
hilla {
vaadin {
productionMode = true
}
----
Expand All @@ -345,7 +295,7 @@ In [filename]`build.gradle`:

[source,groovy,subs="normal"]
----
hilla {
vaadin {
productionMode = true
}
----
Expand Down Expand Up @@ -384,7 +334,7 @@ plugins {
}
war {
enabled = true
enabled = true
}
----
pass:[<!-- vale Vale.Spelling = NO -->]
Expand Down Expand Up @@ -453,18 +403,18 @@ 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 Hilla 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 'com.vaadin.hilla' version "$hillaVersion"
// id 'com.vaadin' version "$vaadinVersion" // should be commented out
}
apply plugin: 'dev.hilla' // this is how it works in case of using pre-releases
apply plugin: 'com.vaadin' // should be added in case of using pre-releases
----

Add `buildscript` to the [filename]`settings.gradle` file containing the following:
Expand All @@ -482,12 +432,12 @@ buildscript {
maven { url = 'https://maven.vaadin.com/vaadin-prereleases' }
}
dependencies {
classpath "dev.hilla:hilla-gradle-plugin:$hillaVersion"
classpath "com.vaadin:vaadin-gradle-plugin:$vaadinVersion"
}
}
----

You can now try out pre-release and snapshot versions of Hilla and the Hilla Gradle Plugin.
You can now try out pre-release and snapshot versions of Vaadin and the Vaadin Gradle plugin.

.Use Final Releases for Production.
[NOTE]
Expand Down

0 comments on commit 4acb3e7

Please sign in to comment.