HTMX: Getting Started

Enable the viewer

First configure the rich GraphQL backend. Add this dependency using the same Causeway version as the application:

<dependency>
    <groupId>org.apache.causeway.viewer</groupId>
    <artifactId>causeway-viewer-webcomponents-htmx</artifactId>
    <version>${causeway.version}</version>
</dependency>

Import org.apache.causeway.viewer.webcomponents.htmx.CausewayModuleViewerWebcomponentsHtmx in the application bootstrap alongside the GraphQL and domain modules. The foundation alone does not install HTMX routes. The host packages HTMX 2.0.6 and its own bridge and shell stylesheet beneath /causeway-htmx/; do not add a second CDN copy.

The default entry point is /htmx, and the GraphQL endpoint defaults to /graphql. An ordinary request receives a complete document; enhanced navigation replaces only the route fragment. Menus and the client context stay connected across route changes.

Run Petclinic

From the repository root, with the development prerequisites installed:

./viewers/webcomponents/sample-htmx-petclinic/run.sh

Open http://localhost:8080/htmx. The root URL redirects there, and the ordinary sample also offers Wicket comparison at http://localhost:8080/wicket/. Use the application menu to find an owner, open its object page, and navigate to a pet and visit. Observe the stable menu while the route changes, then use Back and Forward to check restoration. Try a supported property edit or action and observe server validation and result presentation.

For direct comparison with Vue, Mary Smith’s sample route is /htmx/object/petclinic.PetOwner/s_owner-mary. The sample supplies custom owner, pet, and visit pages; types without an exact registration use the generic object page. Treat the unprotected comparison application as a development sample, not a deployment security template.

The launcher accepts JAVA_HOME, an optional MVN executable, and additional Maven arguments. Stop it before starting the secured sample or the Vue sample on the same port.

Next steps