Skip to content

docs: document Hilla sourceClasses/mainClass endpoint discovery configuration #5659

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
Artur- wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document Hilla sourceClasses/mainClass endpoint discovery configuration #5659

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
49 changes: 49 additions & 0 deletions articles/hilla/lit/reference/configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,55 @@
[NOTE]
If endpoints external to the main application have autowired Spring dependencies, make sure that Spring can find them. Otherwise, Hilla tries to instantiate them using a default no-arguments constructor, which won't trigger dependency injection.


[[endpoint-discovery]]
[role="since:com.vaadin:vaadin@V25.2"]
== Explicit Endpoint Discovery

During code generation, Hilla discovers browser-callable classes -- classes annotated with [annotationname]`@BrowserCallable` or [annotationname]`@Endpoint` -- automatically. The discovery relies on detecting the Spring Boot application class on the module's classpath. In some setups, such as multi-module projects where the application class resides in a different module, this auto-detection fails.

In these cases, you can configure endpoint discovery explicitly with the `mainClass` and `sourceClasses` plugin parameters. They are available on the `prepare-frontend`, `build-frontend`, and `generate` goals of the Hilla Maven plugin:

`mainClass`::
The fully qualified name of the Spring Boot application class to use for discovering browser-callable classes.

`sourceClasses`::
A 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.

Check warning on line 93 in articles/hilla/lit/reference/configuration.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Abbr] 'AOT' has no definition.

Raw Output:
{"message": "[Vaadin.Abbr] 'AOT' has no definition.", "location": {"path": "articles/hilla/lit/reference/configuration.adoc", "range": {"start": {"line": 93, "column": 145}}}, "severity": "WARNING"}

For example, to set the application class explicitly:

[source,xml]
----
<plugin>
<groupId>com.vaadin.hilla</groupId>
<artifactId>hilla-maven-plugin</artifactId>
<version>${hilla.version}</version>
<configuration>
<mainClass>com.example.application.Application</mainClass>
</configuration>
</plugin>
----

Alternatively, if there is no Spring Boot application class available, list the Spring configuration classes that declare the browser-callable beans:

[source,xml]
----
<plugin>
<groupId>com.vaadin.hilla</groupId>
<artifactId>hilla-maven-plugin</artifactId>
<version>${hilla.version}</version>
<configuration>
<sourceClasses>
<sourceClass>com.example.application.ApplicationConfiguration</sourceClass>
<sourceClass>com.example.module.ModuleConfiguration</sourceClass>
</sourceClasses>
</configuration>
</plugin>
----

[NOTE]
When either `mainClass` or `sourceClasses` is set, Hilla discovers browser-callable classes with the Spring AOT-based finder, and skips the default lookup-based auto-detection.

Check warning on line 127 in articles/hilla/lit/reference/configuration.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Abbr] 'AOT' has no definition.

Raw Output:
{"message": "[Vaadin.Abbr] 'AOT' has no definition.", "location": {"path": "articles/hilla/lit/reference/configuration.adoc", "range": {"start": {"line": 127, "column": 109}}}, "severity": "WARNING"}

[[ts-compiler-options]]
== TypeScript Compiler Options

Expand Down
50 changes: 50 additions & 0 deletions articles/hilla/lit/reference/gradle.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,56 @@
----
You can find more details about production builds in the <<#_production, Going to Production>> section.

[#_endpoint_discovery]
[role="since:com.vaadin:vaadin@V25.2"]
=== Explicit Endpoint Discovery

During code generation, Hilla discovers browser-callable classes -- classes annotated with [annotationname]`@BrowserCallable` or [annotationname]`@Endpoint` -- automatically. The discovery relies on detecting the Spring Boot application class on the module's classpath. In some setups, such as multi-module projects where the application class resides in a different module, this auto-detection fails.

In these cases, you can configure endpoint discovery explicitly with the following project properties:

`com.vaadin.hilla.mainClass`::
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.

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

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Abbr] 'AOT' has no definition.

Raw Output:
{"message": "[Vaadin.Abbr] 'AOT' has no definition.", "location": {"path": "articles/hilla/lit/reference/gradle.adoc", "range": {"start": {"line": 304, "column": 161}}}, "severity": "WARNING"}

Set the properties in the [filename]`gradle.properties` file:

[source,properties]
----
com.vaadin.hilla.mainClass=com.example.application.Application
----

Alternatively, if there is no Spring Boot application class available, list the Spring configuration classes that declare the browser-callable beans:

[source,properties]
----
com.vaadin.hilla.sourceClasses=com.example.application.ApplicationConfiguration,com.example.module.ModuleConfiguration
----

You can also pass the properties on the command line:

[.example]
--
.terminal
[source,bash,subs="+attributes"]
----
<source-info group="Windows"></source-info>
gradlew -Pcom.vaadin.hilla.mainClass=com.example.application.Application hillaGenerate
----

.terminal
[source,bash,subs="+attributes"]
----
<source-info group="macOS / Linux"></source-info>
./gradlew -Pcom.vaadin.hilla.mainClass=com.example.application.Application hillaGenerate
----
--

[NOTE]
When either property is set, Hilla discovers browser-callable classes with the Spring AOT-based finder, and skips the default lookup-based auto-detection.

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

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Abbr] 'AOT' has no definition.

Raw Output:
{"message": "[Vaadin.Abbr] 'AOT' has no definition.", "location": {"path": "articles/hilla/lit/reference/gradle.adoc", "range": {"start": {"line": 340, "column": 87}}}, "severity": "WARNING"}

[#_production]
== 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.
Expand Down
Loading