Skip to content

doc: Improve Gradle plugin documentation (V24) #5476

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

Open
mcollovati wants to merge 1 commit into
base: v24
Choose a base branch
from
Open

doc: Improve Gradle plugin documentation (V24) #5476

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
9 changes: 9 additions & 0 deletions articles/flow/configuration/development-mode/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,15 @@
</plugin>
----

[source,groovy]
.build.gradle

Check failure on line 130 in articles/flow/configuration/development-mode/index.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'Gradle' instead of 'gradle'.

Raw Output:
{"message": "[Vale.Terms] Use 'Gradle' instead of 'gradle'.", "location": {"path": "articles/flow/configuration/development-mode/index.adoc", "range": {"start": {"line": 130, "column": 8}}}, "severity": "ERROR"}
----
<source-info group="Vaadin Gradle Plugin"></source-info>
vaadin {
frontendHotdeploy = true
}
----

[source,xml]
.pom.xml
----
Expand Down
19 changes: 19 additions & 0 deletions articles/flow/configuration/gradle.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ vaadin {

If the parameter is `true`, it enables development using the frontend development server instead of an application bundle. This applies only to development mode.

[IMPORTANT]
The Vaadin Gradle plugin does not read configuration from `application.properties`. Setting `vaadin.frontend.hotdeploy=true` in `application.properties` only affects the application at runtime. To control plugin behavior during builds, set the corresponding property in the `vaadin {}` block in [filename]`build.gradle`.


[[build-file.repositories]]
=== Configuring Repositories
Expand Down Expand Up @@ -88,6 +91,8 @@ The Vaadin-related tasks handled by the plugin are as follows:

`vaadinPrepareFrontend`::
This step verifies that Node.js and `npm` are installed, copies the frontend resources, and, if needed, creates or updates the [filename]`package.json` file and Vite configuration files (i.e., [filename]`vite.config.ts` and [filename]`vite.generated.ts`). The frontend resources are located within `.jar` dependencies and are copied to `src/main/frontend/generated/jar-resources`.
+
This task is automatically attached to the `processResources` Gradle lifecycle task. This means it runs on every compilation, including when your IDE triggers an automatic build (e.g., IntelliJ IDEA's default Gradle build delegation). In hot deploy mode, this can cause generated frontend files like `index.ts` to be deleted if `frontendHotdeploy` is not set in the `vaadin {}` block. See <<known-issues,Known Issues>> for workarounds.

`vaadinBuildFrontend`::
This builds the frontend bundle with the `Vite` utility. Vaadin frontend resources (e.g., HTML, JavaScript, CSS, and images) are bundled to optimize loading the frontend. This task isn't executed automatically on the `build` and other targets, so you'll need to run it, explicitly.
Expand Down Expand Up @@ -242,6 +247,9 @@ Indicates that the application is running in production mode. Defaults to `false
`forceProductionBuild: Boolean = false`::
Whether to generate a production bundle even if an existing pre-compiled bundle could be used. A value of 'true' forces bundle generation without validating if there is a usable production bundle already.

`frontendHotdeploy: Boolean = false`::
Enables development using the frontend development server instead of an application bundle. This applies only to development mode. This must be set in the `vaadin {}` block; the Gradle plugin does not read the corresponding `vaadin.frontend.hotdeploy` property from `application.properties`.

`frontendOutputDirectory: File = null`::
The folder where Vite should output [filename]`index.js` and other generated files. Defaults to `null`, which uses the automatically detected value of the main SourceSet, usually `build/resources/main/META-INF/VAADIN/webapp/`.

Expand Down Expand Up @@ -321,3 +329,14 @@ When the list of dependencies causes the classpath to go over a set limit on Win

You can fix this in two ways: add the repository `mavenLocal()` to <<#build-file.repositories,build file repositories>>; or specify the `vaadin.allowed-packages` property, see <<{articles}/flow/integrations/spring/configuration#,Vaadin Spring Configuration>>.

=== IntelliJ IDEA and Gradle

By default, IntelliJ IDEA delegates build and run actions to Gradle. This means that every time you edit a file or switch focus, IDEA may trigger a Gradle compilation, which in turn executes `vaadinPrepareFrontend`. This can interfere with hot deploy by deleting and regenerating frontend files.

To avoid this:

1. Set `frontendHotdeploy = true` in the `vaadin {}` block in [filename]`build.gradle` (not only in [filename]`application.properties`). This ensures the Gradle plugin is aware of hot deploy mode during builds.
2. Alternatively, configure IntelliJ IDEA to build using its own compiler instead of Gradle: go to *Settings* > *Build, Execution, Deployment* > *Build Tools* > *Gradle* and under *Build and run using*, select *IntelliJ IDEA*.

See <<{articles}/getting-started/run/intellij#,Run in IntelliJ IDEA>> for more details.

2 changes: 1 addition & 1 deletion articles/flow/configuration/properties.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,7 +221,7 @@ Bundle parameter controls parts of frontend bundle creation.

|`frontend.hotdeploy`
|`vaadin.frontend.hotdeploy`
|Enables development using the frontend development server instead of an application bundle. This applies only to development mode. Hilla always forces frontend `hotdeploy` to true.
|Enables development using the frontend development server instead of an application bundle. This applies only to development mode. Hilla always forces frontend `hotdeploy` to true. This is a runtime property read by the application. For Gradle projects, the Gradle plugin requires separate configuration via the `frontendHotdeploy` option in the `vaadin {}` block (see <<{articles}/flow/configuration/gradle#build-file.vaadin-options,Vaadin Plugin Configuration>>).
|`false`
|Development

Expand Down
15 changes: 15 additions & 0 deletions articles/getting-started/run/intellij.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,21 @@ image::images/idea-debug.png[Debug button in IntelliJ IDEA]

The application starts up and you can access it at http://localhost:8080. Hot deploy of the frontend files is enabled automatically. However, to enable Java hotswap, you have to take some additional actions.

== Gradle Projects

By default, IntelliJ IDEA delegates build and run actions to Gradle for Gradle-based projects. For a better development experience, configure IntelliJ IDEA to build and run using its own compiler instead:

1. Go to *Settings* > *Build, Execution, Deployment* > *Build Tools* > *Gradle*.
2. Under *Build and run using*, select *IntelliJ IDEA*.
3. Under *Run tests using*, select *IntelliJ IDEA*.

This avoids unnecessary Gradle task execution during development and provides faster compilation.

[TIP]
====
When using hot deploy with Gradle, ensure that `frontendHotdeploy` is set to `true` in the `vaadin {}` block in [filename]`build.gradle`, not only in [filename]`application.properties`. The Gradle plugin does not read `application.properties`. See <<{articles}/flow/configuration/gradle#build-file.vaadin-options,Vaadin Plugin Configuration>> for details.
====


== Enabling Hotswap

Expand Down
Loading