Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: fix outdated information on Hilla Gradle article #3718

Merged
merged 5 commits into from
Sep 26, 2024
Merged

fix: fix outdated information on Hilla Gradle article #3718

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ddf161c
fix: fix outdated information
taefi Sep 25, 2024
1fa3d4a
Merge branch 'latest' into taefi/fix-hilla-gradle-article
taefi Sep 25, 2024
809751b
fix lint errors
taefi Sep 26, 2024
fb72f83
Merge branch 'latest' into taefi/fix-hilla-gradle-article
taefi Sep 26, 2024
28b33ca
fix lint errors
taefi Sep 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 49 additions & 99 deletions articles/hilla/lit/reference/gradle.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,21 @@
: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.

Check warning on line 23 in articles/hilla/lit/reference/gradle.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/hilla/lit/reference/gradle.adoc", "range": {"start": {"line": 23, "column": 7}}}, "severity": "WARNING"}

[#_requirements]
== Requirements
Expand All @@ -42,15 +45,15 @@

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

----
[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 @@

[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 @@

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

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

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

[source,groovy,subs="normal"]
----
hilla {
vaadin {
productionMode = true
}
----
Expand Down Expand Up @@ -384,7 +334,7 @@
}

war {
enabled = true
enabled = true
}
----
pass:[<!-- vale Vale.Spelling = NO -->]
Expand Down Expand Up @@ -453,18 +403,18 @@
}
----

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 @@
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
Loading