Forem: Thomas

Spring Modulith vs Multi-Module projects - advantages and disadvantages

Thomas — Fri, 14 Nov 2025 09:43:37 +0000

Modularization is the most important factor for the long-term maintainability of a growing codebase. Two powerful options are available for Spring Boot projects: Spring Modulith and a multi-module setup. How do they differ, and which approach should you choose for your project?

Spring Modulith and Multi-Module explained

With Spring Modulith, the main focus is on splitting the actual Java or Kotlin code into modules. Under a main package (for example my/company/app) all subpackages are treated as modules (for example product, inventory). Access to another module is only possible through a defined interface - usually a service in the top-level package of a module as well as other packages that are explicitly exposed. Internal details like repositories and entities are not available.

The entire structure is verified by the spring-modulith libraries. Other artifacts are taken from src/main/resources, just like in a monolith. With this approach, practically all external libraries of the application can be used without restrictions.

Multi-module projects are based on the native ability of Gradle or Maven to manage multiple subprojects and integrate them into the build process using the Spring Boot plugin. Each module has its own folder in the project (for example app/product, app/inventory) and each module has its own src/main/java (or src/main/kotlin) and src/main/resources folders. These modules are built as real jars - in the final executable fat jar, all other libraries are included again.

Differences in practice

An existing monolith can be converted to a Spring Modulith project relatively quickly - you only need to add the dependency and change the package structure. IntelliJ even shows the modules and breaches directly. Hardly any changes are needed in the code itself, only the module interfaces must be defined and used correctly.

For multi-module projects, no additional library is required, but the build files (build.gradle, build.gradle.kts or pom.xml) need much more adjustment. Access is only possible along the defined dependency path - imports outside of the integrated modules are technically not possible. Restricting access to internal classes is not built in and should be defined through coding guidelines rather than code restrictions.

For integration tests that cover the entire application, both approaches achieve a similar goal but in different ways.

With Spring Modulith, the annotation @ApplicationModuleTest with BootstrapMode.ALL_DEPENDENCIES is used. This runs a test in the current module including all dependent modules. Since Spring Modulith determines modules at runtime based on actual dependencies, missing modules may need to be added via extraIncludes. This can be the case, for example, if a module only contains configuration and has no exposed services.
For multi-module projects, module dependencies are always explicitly defined in the build files (for example api project(':product') in a build.gradle). When integration tests with @SpringBootTest are run, the application automatically starts with the context available for that module. Since each module also provides its own resources, only those are actually available (for example, only the included Flyway scripts are executed).

Some libraries also require additional configuration to operate in a multi-module setup. While libraries like Flyway and Thymeleaf work almost out of the box, support for others such as jte is missing completely and must be provided separately.

Choosing an approach

Both modularization approaches achieve the main goal of logically splitting the code and thus ensuring long-term maintainability. This makes both approaches clearly better than a monolith, often called the “big ball of mud.” In both cases, it is important to design the module structure around your domain, not around technical layers - so better product, inventory, order instead of services, controller, frontend. More details in best practices for multi-module projects.

Spring Modulith differs less from a monolith, so the learning and configuration effort is smaller. Interfaces need to be clearly defined, which can be either an advantage or a disadvantage. A special test can also generate documentation of the current module structure.

The higher setup effort of multi-module projects comes with the benefit of real, logical modules. All artifacts are directly assigned to a module, making it easier to split work within a team. The code itself is not aware of the modules, since the structure is managed by Maven or Gradle.

Overview of modularization options in Spring Boot

In both approaches, individual modules can later be separated into microservices if needed. However, this step should be carefully considered - architecture is not an end in itself, but the added benefits should clearly outweigh the new costs.

In the Bootify Builder, you can create a modularized Spring Boot app using either Spring Modulith or the multi-module approach. Define your custom module structure, including the assignments of entities and Spring Security configs, and get the full setup directly in the browser.

» See Features and Pricing

Integrate jte with Spring Boot

Thomas — Wed, 27 Aug 2025 13:27:20 +0000

Jte is a modern template engine for Spring Boot that stands out for its minimalist syntax. What steps are necessary to integrate jte into our application and make it ready for use in the real world?

The current sample code for the setup described is available here.

Application configuration

The starting point is a Spring Boot application based on Maven without a frontend. We can easily create this using Bootify with start project. We could already choose jte as the frontend, however we would like to manually review the exact steps involved.

First, we expand our pom.xml with the following points.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <!-- ... -->
    <dependencies>
        <dependency>
            <groupId>gg.jte</groupId>
            <artifactId>jte-spring-boot-starter-3</artifactId>
            <version>3.2.1</version>
        </dependency>
        <dependency>
            <groupId>gg.jte</groupId>
            <artifactId>jte</artifactId>
            <version>3.2.1</version>
        </dependency>
        <dependency>
            <groupId>org.webjars</groupId>
            <artifactId>bootstrap</artifactId>
            <version>5.3.7</version>
        </dependency>
        <!-- ... -->
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <profiles>
                        <profile>local</profile>
                    </profiles>
                </configuration>
            </plugin>
            <plugin>
                <groupId>gg.jte</groupId>
                <artifactId>jte-maven-plugin</artifactId>
                <version>3.2.1</version>
                <configuration>
                    <sourceDirectory>${project.basedir}/src/main/jte</sourceDirectory>
                    <targetDirectory>${project.build.directory}/classes</targetDirectory>
                    <contentType>Html</contentType>
                </configuration>
                <executions>
                    <execution>
                        <phase>process-classes</phase>
                        <goals>
                            <goal>precompile</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

New dependencies and plugin config for jte

This adds jte, Bootstrap as a WebJar and a Spring Boot starter that expects all templates to be located in src/main/jte. To ensure that these are recompiled during development after every change, we add an application-local.properties file with the following entries to our project.

gg.jte.usePrecompiledTemplates=false
gg.jte.developmentMode=true

During development, the local profile should be active so that these settings are used. We extend the existing application.properties with the following setting.

gg.jte.usePrecompiledTemplates=true

Precompiled templates are expected in the classpath with this setting - this is already handled by our configured plugin, which stores all artifacts in target/classes so that they are integrated into our fat jar.

We need a helper to make further required functions available in our templates. To avoid having to define and pass an object as a parameter everywhere, we use a helper class with static methods.

public class JteContext {

    private static final LocalizationSupport localizer = WebUtils::getMessage;
    private static final ThreadLocal<ModelMap> model = new ThreadLocal<>();

    public static void init(final ModelMap model) {
        JteContext.model.set(model);
    }

    public static void reset() {
        JteContext.model.remove();
    }

    public static Content localize(final String key, final Object... params) {
        return localizer.localize(key, params);
    }

    public static ModelMap getModel() {
        return model.get();
    }

    public static String getMsgSuccess() {
        return ((String)model.get().getAttribute(WebUtils.MSG_SUCCESS));
    }

    public static String getMsgInfo() {
        return ((String)model.get().getAttribute(WebUtils.MSG_INFO));
    }

    public static String getMsgError() {
        return ((String)model.get().getAttribute(WebUtils.MSG_ERROR));
    }

    public static String getRequestUri() {
        return WebUtils.getRequest().getRequestURI();
    }

}

Helper methods for our templates

The LocalizationSupport is the recommended interface for internationalization. An interceptor is responsible for setting and removing the model for the duration of a request.

@Component
public class JteContextInterceptor implements HandlerInterceptor {

    @Override
    public void postHandle(final HttpServletRequest request, final HttpServletResponse response,
            final Object handler, final ModelAndView modelAndView) {
        if (modelAndView != null) {
            JteContext.init(modelAndView.getModelMap());
        }
    }

    @Override
    public void afterCompletion(final HttpServletRequest request,
            final HttpServletResponse response, final Object handler, final Exception ex) {
        JteContext.reset();
    }

}

This allows us to use all defined functions in our templates using @import static io.bootify.jte.util.JteContext.* and extend them as needed.

Layout and first pages

Real enterprise applications usually require a number of features that we want to integrate into our application. Firstly we want to add a layout.jte. In abbreviated form, it looks like this - including a parameter content, which we use to integrate the actual content of a template.

@import static io.bootify.jte.util.JteContext.*

@param gg.jte.Content pageTitle
@param gg.jte.Content content


<!DOCTYPE html>
<html lang="en">
    <head>
        <title>${pageTitle} - ${localize("app.title")}</title>
        <link href="/webjars/bootstrap/5.3.7/css/bootstrap.min.css" rel="stylesheet" />
        <script src="/webjars/bootstrap/5.3.7/js/bootstrap.bundle.min.js" defer></script>
    </head>
    <body>
        <header class="bg-light">
            <div class="container">
                <nav class="navbar navbar-light navbar-expand-md">
                    <a href="/" class="navbar-brand">
                        <img src="/images/logo.png" alt="${localize("app.title")}" width="30" height="30" class="d-inline-block align-top" />
                        <span class="ps-1">${localize("app.title")}</span>
                    </a>
                </nav>
            </div>
        </header>
        <main class="my-5">
            <div class="container">
                @if (getMsgSuccess() != null)
                    <p class="alert alert-success mb-4" role="alert">${getMsgSuccess()}</p>
                @elseif (getMsgInfo() != null)
                    <p class="alert alert-info mb-4" role="alert">${getMsgInfo()}</p>
                @elseif (getMsgError() != null)
                    <p class="alert alert-danger mb-4" role="alert">${getMsgError()}</p>
                @endif
                ${content}
            </div>
        </main>
    </body>
</html>

A simple jte layout

This allows us to continue with the actual pages. A file src/main/jte/error.jte is automatically picked up by Spring Boot for error pages.

@import static io.bootify.jte.util.JteContext.*

@param Integer status
@param String error


@template.layout(pageTitle=localize("error.page.headline", status, error), content=@`
    <h1 class="mb-4">${status} - ${error}</h1>
    <p>${localize("error.page.message")}</p>
`)

A simple error page

Here, we are using our prepared layout directly - the principle is clear. A homepage could look like this.

@import static io.bootify.jte.util.JteContext.*


@template.layout(pageTitle=localize("home.index.headline"), content=@`
    <h1 class="mb-4">${localize("home.index.headline")}</h1>
    <p class="mb-5">${localize("home.index.text")}</p>
    <div class="col-md-4 mb-5">
        <h4 class="mb-3">${localize("home.index.exploreEntities")}</h4>
        <div class="list-group">
            <a href="/products" class="list-group-item list-group-item-action">${localize("product.list.headline")}</a>
        </div>
    </div>
`)

We have already completed all necessary steps so that our application compiles and displays jte templates.

More complex setups

The next step is to make our application support forms based on Spring MVC. There are no direct functions from jte for this - instead, we can extend our JteContext class with practical helpers.

public class JteContext {

    // ...

    public static BindingResult getBindingResult(final String object) {
        final BindingResult bindingResult = ((BindingResult)model.get().getAttribute(
                "org.springframework.validation.BindingResult." + object));
        if (bindingResult == null) {
            return emptyBindingResult;
        }
        return bindingResult;
    }

    public static String getFieldValue(final String object, final String field) {
        return ((String)getBindingResult(object).getFieldValue(field));
    }

    @SuppressWarnings("unchecked")
    public static <T> T getFieldValue(final String object, final String field,
            final Class<T> type) {
        final Object dto = model.get().getAttribute(object);
        if (dto == null) {
            return null;
        }
        try {
            final Field classField = dto.getClass().getDeclaredField(field);
            classField.setAccessible(true);
            return ((T)classField.get(dto));
        } catch (final Exception ex) {
            throw new RuntimeException(ex);
        }
    }

}

Extensions for form handling

The second variant of getFieldValue is needed to obtain the value with its actual type. Jte templates are always compiled into real Java code, so casting may be necessary. Additional functions such as isAuthenticated() for Spring Security can be added to JteContext as needed.

Complete CRUD functionality and an inputRow.jte template can be seen in the Spring Boot jte example.

Jte's minimalist approach is very appealing, especially if you are used to the complexity of Thymeleaf. Although you have to write your own helpers for some important features, the code is very easy to understand and extend.

» Learn more

The JHipster alternative for modern Spring Boot apps

Thomas — Sat, 09 Aug 2025 12:37:03 +0000

JHipster is a long established OpenSource framework to generate and run Java applications. New apps are created based on a custom syntax (JDL), which also includes the database schema.

Bootify also allows the generation of modern microservices and web applications. As with JHipster, it simplifies the creation of entities and provides CRUD functionality for the frontend and REST API. Bootify is based on a freemium model and runs completely in the browser.

"Thanks for making such a neat tool. It's like a cleaner, sensible JHipster!"

-- Joachim D., Senior Software Developer

What are the advantages of Bootify over JHipster?

Pure Spring Boot without vendor lock-in

Application development with JHipster is done with its own library and CLI to continuously maintain an application, even after the initial creation. However, this also imposes processes that must be learned and followed. Bootify generates pure Spring Boot applications following best practices, so a developer does not need to have any specific knowledge.

Follow your own preferences

Numerous features are available in Bootify or Spring Boot that cannot be implemented with JHipster. For example, Bootify can be used to prepare an application with Lombok or multiple modules. The frontend can be based on Thymeleaf (SSR), Angular or React (SPA), following their current recommendations for the development approach and syntax.

Start with the concept

Individual preferences, database schema, REST APIs and frontend forms can be specified in the browser before writing the first line of code. This allows to iteratively improve the concept as a team before the runnable application is downloaded.

Review your generated code in the browser

Build prototypes for the real world

Production-focused applications are mostly not limited to pure CRUD functions, but implement actual use cases. For this purpose, custom REST APIs and forms can be designed in Bootify's Professional plan. The generated code contains only the necessary elements and no overhead that requires long-term maintenance.

When should Bootify be chosen?

JHipster enables the creation of solid applications, especially if the technology is already used and established in the company. For new applications you have to evaluate if the provided features are exactly what you need - deviations from the given path in JHipster are not possible at all or only with high effort.

Using Bootify, only the exact code needed for your chosen configuration is generated, thus providing a lightweight alternative to JHipster. The application can be reviewed online by the entire team and is completely under your control once downloaded.

» See Features and Pricing

Integrating Spring Boot with Angular

Thomas — Sat, 28 Jun 2025 13:19:04 +0000

Angular is a powerful, mature library for single page applications. While Angular runs completely in the client, Spring Boot can be used to provide the backend with all its functions. What are the steps to integrate Angular in its current version 20 into our Spring Boot app?

Using Bootify, a Spring Boot application with Angular as the frontend stack can be created directly in the browser - start project here. All the points described below are already implemented and further settings can be selected according to your preferences. In order to understand the following steps, we will start with a simple application from Bootify without a frontend.

In general, we try to follow the recommendations and standards of both frameworks in their current version as closely as possible - but a few adjustments are necessary so that both work together optimally and all development processes are supported.

Angular setup

A new Angular client is created with its CLI (when not using Bootify). Node.js must be available on the system first; then we add the CLI as a global dependency.

npm install -g @angular/cli

We then create our new Anguar project - the subfolder is created automatically. We select SCSS as the language for the styles and server-side rendering is not supported.

ng new angularclient

We now move the generated client application completely into our Spring project. In addition to the top-level files, the actual client code is located in the src folder. Since this does not fit well with the structure of Java applications, we move this code to src/main/webapp instead. We keep the .gitignore of our Spring application and only add the line /node_modules there.

We can then write the new folder name into our angular.json and also adjust the target folders - for a Maven project this is target/classes/static, whereas for Gradle it is build/resources/main/static. We should also set the browser setting to "" so that we don't get an extra folder on top.

{
  // ...
  "projects": {
    "angularclient": {
      "projectType": "application",
      "schematics": {
        "@schematics/angular:component": {
          "style": "scss"
        }
      },
      "root": "",
      "sourceRoot": "src/main/webapp",
      "prefix": "app",
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:application",
          "options": {
            "outputPath": {
              "base": "./target/classes/static",
              "browser": ""
            },
            "index": "src/main/webapp/index.html",
            "main": "src/main/webapp/main.ts",
            "polyfills": [
              "zone.js"
            ],
            "tsConfig": "tsconfig.app.json",
            "inlineStyleLanguage": "scss",
            "assets": [
              "src/main/webapp/favicon.ico",
              {"glob": "**/*", "input": "src/main/webapp/public"}
            ],
            "styles": [
              "src/main/webapp/styles.scss"
            ],
            "scripts": []
          },
    // ...
}

Adjusting our client configuration

With this setup, our client should be ready to run again in its new home. We install the dependencies once and then start the development server. Our application should then be available at http://localhost:4200.

npm install
ng serve

Spring Boot integration

Our client application could not yet call the REST API of our backend during development, because our Spring application is reachable there under port 8080 and a CORS error would occur. Therefore, we add a small configuration to our app that only becomes active for the local profile.This way the browser will no longer block our API calls.

@Configuration
@Profile("local")
public class AngularLocalConfig {

    @Bean
    public WebMvcConfigurer corsConfigurer() {
        return new WebMvcConfigurer() {
            @Override
            public void addCorsMappings(final CorsRegistry registry) {
                registry.addMapping("/**").allowedMethods("*").allowedOrigins("http://localhost:4200");
            }
        };
    }

}

Allowing API calls during development

The only thing missing is the setup so that our Angular client is also accessible after the build and deployment. To do this, we first add a special forward: for all requests that do not correspond to a defined exception, Angular's index.html is rendered. The browser client then has the responibility of showing the correct content according to the URL.

@Controller
public class AngularForwardController {

    @GetMapping("{path:^(?!api|public|swagger)[^\\.]*}/**")
    public String handleForward() {
        return "forward:/";
    }

}

To ensure that our Angular client is build and included in the Spring application (the jar), we use the frontend-maven-plugin for Maven or the gradle-node-plugin for Gradle.

<plugin>
    <groupId>com.github.eirslett</groupId>
    <artifactId>frontend-maven-plugin</artifactId>
    <version>1.15.1</version>
    <executions>
        <execution>
            <id>nodeAndNpmSetup</id>
            <goals>
                <goal>install-node-and-npm</goal>
            </goals>
        </execution>
        <execution>
            <id>npmInstall</id>
            <goals>
                <goal>npm</goal>
            </goals>
            <configuration>
                <arguments>install</arguments>
            </configuration>
        </execution>
        <execution>
            <id>npmRunBuild</id>
            <goals>
                <goal>npm</goal>
            </goals>
            <configuration>
                <arguments>run build</arguments>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <nodeVersion>v22.16.0</nodeVersion>
    </configuration>
</plugin>

Configuration of the frontend-maven-plugin for Angular

plugins {
    // ...
    id 'com.github.node-gradle.node' version '7.1.0'
}

// ...

node {
    download.set(true)
    version.set('22.16.0')
}

tasks.register('npmRunBuild', NpmTask) {
    args = ['run', 'build']
    dependsOn npmInstall

    inputs.files(fileTree('node_modules'))
    inputs.files(fileTree('src/main/webapp'))
    inputs.file('angular.json')
    inputs.file('package.json')
    inputs.file('tsconfig.json')
    inputs.file('tsconfig.app.json')
    outputs.dir(layout.buildDirectory.dir('resources/main/static'))
}

processResources {
    dependsOn npmRunBuild
}

Integration of the Angular build step

The quickest way to test our new settings is to use mvnw spring-boot:run or gradlew bootRun. This will completely build our Spring Boot app including the frontend and then start it. Our application should now be accessible under http://localhost:8080!

In the Free plan of Bootify, Spring Boot prototypes can be created with Angular and Bootstrap or Tailwind CSS. CRUD functionality for the tables of your custom database schema can be activated as well. The Professional plan includes advanced options such as Spring Security - start your new project in no time and with a strong foundation.

» See Features and Pricing

Htmx error handling in Spring Boot apps

Thomas — Fri, 25 Apr 2025 15:24:25 +0000

Htmx is a fantastic library to simplify web application development and render most of the HTML directly in the backend. However when making calls to the server, expected and unexpected errors can occur - how they are handled best in our Spring Boot application?

Let's assume we already have our Spring Boot application with Thymeleaf and htmx prepared - more details here. Let's add an endpoint to the HomeController that throws an exception - in the real world this could occur, for example, if the database is not available.

@Controller
public class HomeController {

    @GetMapping("/")
    public String index() {
        return "home/index";
    }

    @GetMapping("/fail")
    public String fail() {
        throw new RuntimeException("Failed!");
    }

}

Adding an endpoint producing an "unexpected" error

The Thymeleaf template resources/templates/error.html is added to the repository, which will be picked up and rendered by Spring Boot when an Exception occurs.

<!DOCTYPE HTML>
<html xmlns:th="http://www.thymeleaf.org">
    <head>
        <title>[[${status}]] - [[${error}]]</title>
    </head>
    <body>
        <h1>[[${status}]] - [[${error}]]</h1>
        <p>[[#{error.message}]]</p>
    </body>
</html>

Our very simple error template

If we now call our endpoint directly via http://localhost:8080/fail in the browser, the user sees our prepared template - as it should be. The situation however is different if the page is loaded by htmx via an AJAX request. This could happen for example if the hx-boost="true" flag is set on the body tag in the page http://localhost:8080/ - in this case, the user would receive no feedback at all in the browser when clicking on the link.

There are two issues we need to address here:

because AJAX requests are sent with the header Accept: */*, the regular error handling of Spring Boot returns a JSON response
the response has the HTTP status 500, so htmx does not perform swapping in the browser

We can solve these points either in the backend or client part of our application.

Adding a dedicated error handling to our app

In order to display the error page in the browser for htmx requests as well, we can add the following controller to our application.

@Controller
public class HtmxErrorController {

    private final BasicErrorController basicErrorController;

    public HtmxErrorController(final BasicErrorController basicErrorController) {
        this.basicErrorController = basicErrorController;
    }

    @RequestMapping(value = "${server.error.path:${error.path:/error}}", headers = "HX-Request=true")
    @ResponseStatus(HttpStatus.OK)
    public ModelAndView errorHtmx(final HttpServletRequest request,
            final HttpServletResponse response) {
        return basicErrorController.errorHtml(request, response);
    }

}

Special controller for error output of htmx requests

With this we have a new endpoint on the configured error path that outputs regular HTML with HTTP status 200. By specifying the header HX-Request=true it becomes exclusively active for requests by htmx. Since the result is rendered directly via BasicErrorController, we get exactly the same result as on regular error pages.

Error handling in the browser

Alternatively, we can handle the error output in the client without adding the controller. Here we could first customize the Accept header for htmx requests, so the regular error handling in our Spring Boot application will be applied.

<body hx-boost="true" hx-headers="{&quot;Accept&quot;: &quot;text/html&quot;}">
...
</body>

Adjusting the Accept header for htmx requests

However, the HTTP response status would still be 500 in this case - so htmx will not do the swapping by default (see htmx docs). In order to change this behavior, we need to intercept the htmx:beforeSwap event in our JavaScript code and set the shouldSwap property to true in any case.

document.body.addEventListener('htmx:beforeSwap', function(evt) {
    evt.detail.shouldSwap = true;
})

Extending our JavaScript code

With the Bootify Builder a Spring Boot application with database schema and Thymeleaf frontend can be generated. An option to include htmx is available in the Free plan - with this the application already has the hx-boost="true" flag set and the HtmxErrorController is integrated.

» Learn more

Creating Test Jars in Maven for multi-module projects

Thomas — Mon, 03 Mar 2025 12:27:29 +0000

In multi-module projects, individual modules often contain classes or resources that should also be used in modules based on them - e.g. for initializing test users. In Maven, the maven-jar-plugin can be used to create a referenceable test library for this purpose.

Suppose we have a simple Spring Boot application with two modules "base" and "web". An integration test in "web" now needs to access a method initTestUsers, which is stored inside the "src/test/java" section in "base".

First, the pom.xml of the module "base" must be extended to provide a jar of the test classes.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.4.2</version>
            <executions>
                <execution>
                    <goals>
                        <goal>test-jar</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Adding maven-jar-plugin to the module providing the test data

Now the new library can be referenced from "web". The scope "test" makes it available for testing only, so it will not be included in the final "fat jar" of our Spring Boot executable.

<dependency>
    <groupId>${project.groupId}</groupId>
    <artifactId>base</artifactId>
    <classifier>tests</classifier>
    <type>test-jar</type>
    <version>${project.version}</version>
    <scope>test</scope>
</dependency>

Referencing the new test jar

Using Bootify, prototypes for Spring Boot applications can be created within minutes - develop a concept within the team first and then directly focus on the business logic. In the Professional plan, the multi-module option is available, which automatically sets up the maven-jar-plugin for Maven projects.

» Learn more

Form Login with Spring Boot and Thymeleaf

Thomas — Thu, 25 Jul 2024 09:05:18 +0000

The form-based login is often the first choice to protect the web frontend of a Spring Boot application. It ensures that certain areas of our application are only accessible once a user has authenticated himself with a username and password, and this status is stored in the session. What are the steps required to add form based login to our Spring Boot application?

Start with a simple application

First, we use the Bootify Builder to create a simple Spring Boot application in the current version 3.3.2 - to do this, we simply click on open project. There we select Thymeleaf + Bootstrap as frontend stack - Thymeleaf is the most used template engine of Spring Boot and allows server-side rendering. Bootstrap will be integrated into our app as a WebJar. Select any database which you would like to connect to - an embedded database will do for now as well.

In the Entities Tab we create the tables User as well as TodoList, and connect them with an N:1 relation. For the TodoList we activate the CRUD option for the frontend - this will be the area we secure with Spring Security afterwards.

Preview of our very simple database schema

Now we can already download the finished application and import it into our favorite IDE.

The first version of our application in IntelliJ

Configuration of Spring Security

The form-based login is provided with the help of Spring Security. So we first need the relevant dependencies, which we add to our build.gradle or pom.xml respectively.

implementation('org.springframework.boot:spring-boot-starter-security')
implementation('org.thymeleaf.extras:thymeleaf-extras-springsecurity6')

The module spring-boot-starter-security integrates Spring Security. With thymeleaf-extras-springsecurity6 a little helper is included which provides the authentication state in our Thymeleaf templates - more about that later.

With this we can already provide the central security configuration - here directly in our final version.

@Configuration
@EnableMethodSecurity(prePostEnabled = true)
public class HttpSecurityConfig {

    @Bean
    public PasswordEncoder passwordEncoder() {
        return PasswordEncoderFactories.createDelegatingPasswordEncoder();
    }

    @Bean
    public AuthenticationManager authenticationManager(
            final AuthenticationConfiguration authenticationConfiguration) throws Exception {
        return authenticationConfiguration.getAuthenticationManager();
    }

    @Bean
    public SecurityFilterChain configure(final HttpSecurity http) throws Exception {
        return http.cors(withDefaults())
                .csrf(withDefaults())
                .authorizeHttpRequests(authorize -> authorize.anyRequest().permitAll())
                .formLogin(form -> form
                    .loginPage("/login")
                    .usernameParameter("email")
                    .failureUrl("/login?loginError=true"))
                .logout(logout -> logout
                    .logoutSuccessUrl("/login?logoutSuccess=true")
                    .deleteCookies("JSESSIONID"))
                .exceptionHandling(exception -> exception
                    .authenticationEntryPoint(new LoginUrlAuthenticationEntryPoint("/login?loginRequired=true")))
                .build();
    }

}

Our configuration for the form login

Theoretically, Spring Security can provide the login form with less configuration, but this would lack the design and some messages which we would like to present to the user. But let's go through the config first.

BCryptPasswordEncoder is standard nowadays to store the hash of a password together with its individual salt inside a single field. If we don't have a legacy requirement, we should use this one. Also, we provide the AuthenticationManager as a bean to be able to integrate it into other services.

As a third bean we create the SecurityFilterChain as this is the required approach since Spring 3.0. We should configure both CORS and CSRF properly to close the corresponding attack vectors. The default configuration is usually sufficient for this.

At our config class we have placed the annotation @EnableMethodSecurity and will protect the desired controller endpoints with @PreAuthorize(...) later on. Therefore we allow access to the whole application with permitAll(). Without the annotation based security, we should configure the paths to the protected resources at this place as well.

The formLogin() and the logout() methods are customized for our subsequent controller so that we can always display an appropriate message to the user. Spring Security automatically provides an endpoint for the login where username and password can be submitted to via POST request. Here we change the name of the username field to "email". The logout is modified to redirect back to the login page with a parameter afterwards.

Loading users from our database

To load the users from the already created table, we need to provide an implementation of UserDetailsService as a bean - it will be automatically found and used as a user source.

@Service
public class HttpUserDetailsService implements UserDetailsService {

    private final UserRepository userRepository;

    public HttpUserDetailsService(final UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Override
    public HttpUserDetails loadUserByUsername(final String username) {
        final User user = userRepository.findByEmailIgnoreCase(username);
        if (user == null) {
            log.warn("user not found: {}", username);
            throw new UsernameNotFoundException("User " + username + " not found");
        }
        final List<SimpleGrantedAuthority> roles = Collections.singletonList(new SimpleGrantedAuthority("ROLE_USER"));
        return new HttpUserDetails(user.getId(), username, user.getHash(), roles);
    }

}

UserDetailsService implementation automatically used as the user source

In our repository we should add a method User findByEmailIgnoreCase(String email) to execute a search query against the database - ignoring upper/lower case allows the user small mistakes when writing their email. The role here is always ROLE_USER for each user. Since we don't have a registration endpoint available at this point, we can add a simple data loader along with our application for now. The profile "local" is required for it to become active.

@Component
@Profile("local")
public class UserLoader implements ApplicationRunner {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;

    public UserLoader(final UserRepository userRepository,
                      final PasswordEncoder passwordEncoder) {
        this.userRepository = userRepository;
        this.passwordEncoder = passwordEncoder;
    }

    @Override
    public void run(final ApplicationArguments args) {
        if (userRepository.count() != 0) {
            return;
        }
        final User user = new User();
        user.setEmail("test@test.com");
        user.setHash(passwordEncoder.encode("testtest"));
        userRepository.save(user);
    }

}

Helper class to initialize a first user locally

Add login controller

With this we can already add the LoginController. Since the POST endpoint is automatically provided by Spring Security, a GET endpoint is sufficient here to show the template to the user.

@Controller
public class AuthenticationController {

    @GetMapping("/login")
    public String login(@RequestParam(name = "loginRequired", required = false) final Boolean loginRequired,
            @RequestParam(name = "loginError", required = false) final Boolean loginError,
            @RequestParam(name = "logoutSuccess", required = false) final Boolean logoutSuccess,
            final Model model) {
        model.addAttribute("authentication", new AuthenticationRequest());
        if (loginRequired == Boolean.TRUE) {
            model.addAttribute(WebUtils.MSG_INFO, WebUtils.getMessage("authentication.login.required"));
        }
        if (loginError == Boolean.TRUE) {
            model.addAttribute(WebUtils.MSG_ERROR, WebUtils.getMessage("authentication.login.error"));
        }
        if (logoutSuccess == Boolean.TRUE) {
            model.addAttribute(WebUtils.MSG_INFO, WebUtils.getMessage("authentication.logout.success"));
        }
        return "authentication/login";
    }

}

Backend for rendering the login page

The request parameters that we had already specified in our security configuration are converted to corresponding messages here. In our simple application from Bootify the corresponding helpers are already included. Here we also need the AuthenticationRequest object with getters and setters.

public class AuthenticationRequest {

    @NotNull
    @Size(max = 255)
    private String email;

    @NotNull
    @Size(max = 255)
    private String password;

}

The corresponding template for our controller could then look like this.

<!DOCTYPE HTML>
<html xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
        layout:decorate="~{layout}">
    <head>
        <title>[[#{authentication.login.headline}]]</title>
    </head>
    <body>
        <div layout:fragment="content">
            <h1 class="mb-4">[[#{authentication.login.headline}]]</h1>
            <div th:replace="~{fragments/forms::globalErrors('authentication')}" />
            <form th:action="${requestUri}" method="post">
                <div th:replace="~{fragments/forms::inputRow(object='authentication', field='email')}" />
                <div th:replace="~{fragments/forms::inputRow(object='authentication', field='password', type='password')}" />
                <input type="submit" th:value="#{authentication.login.headline}" class="btn btn-primary mt-4" />
            </form>
        </div>
    </body>
</html>

As Thymeleaf doesn't allow direct access to request object anymore, we're providing the requestUri in the model.

@ModelAttribute("requestUri")
String getRequestServletPath(final HttpServletRequest request) {
    return request.getRequestURI();
}

_ Providing the requestUri - as part of the AuthenticationController or a general ControllerAdvice _

With this template we send a POST request to the /login endpoint. The INFO or ERROR messages are automatically displayed by the layout. All used messages have to be present in our messages.properties.

authentication.login.headline=Login
authentication.email.label=Email
authentication.password.label=Password
authentication.login.required=Please login to access this area.
authentication.login.error=Your login was not successful - please try again.
authentication.logout.success=Your logout was successful.
navigation.login=Login
navigation.logout=Logout

Last we can extend our layout.html. With this we also always show a login / logout link in the header. Spring Security also automatically provides a /logout endpoint, but we have to address it via POST.

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
            xmlns:sec="http://www.thymeleaf.org/extras/spring-security">
    <!-- ... -->    
    <a sec:authorize="!isAuthenticated()" th:href="@{/login}" class="nav-link">[[#{navigation.login}]]</a>
    <form sec:authorize="isAuthenticated()" th:action="@{/logout}" method="post" class="nav-link">
        <input th:value="#{navigation.logout}" type="submit" class="unset" />
    </form>
    <!-- ... -->
</html>

Adding login / logout links to our layout

In the html tag we've extended the namespace to use the helpers from the thymeleaf-extras-springsecurity6 module. As a final step we only need to add the annotation @PreAuthorize("hasAuthority('ROLE_USER')") at our TodoListController.

Starting our application

With this we have all needed pieces of our puzzle together! Now we start our application and when we want to see the todo lists, we should be redirected to the login page. Here we can log in with test@test.com / testtest.

Automatic redirect to the login

In the Free plan of Bootify, Spring Boot prototypes with its own database schema, REST API and frontend can be generated. In the Professional plan, among other things, Spring Security with the form-based login is available to generate the setup described here - exactly matching the created database and the selected settings. A registration endpoint and role source can be specified as well.

» See Features and Pricing

Spring Boot with Thymeleaf and Bootstrap

Thomas — Mon, 13 May 2024 09:37:58 +0000

Thymeleaf and Bootstrap are powerful technologies to develop modern web applications. In this article, we will show the steps to add Thymeleaf and Bootstrap to our Spring Boot application.

The complete setup can also be created directly in the Bootify Builder. Just open a project with open project, choose your preferences and select Thymeleaf + Bootstrap as frontend stack. If you don't select a frontend, all the following steps can be followed manually.

Adding Themeleaf to our app

Thymeleaf is the most used template engine for Spring Boot. Since the templates are written in valid HTML code, they can be opened without server-side rendering as well. To setup the engine and all recommended utilities, the following two dependencies are added to our application first.

implementation('org.springframework.boot:spring-boot-starter-thymeleaf')
implementation('nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect')

Adding new dependencies for Thymeleaf

The module spring-boot-starter-thymeleaf will automatically integrate the template engine - in the following controller we can already see how this works. The thymeleaf-layout-dialect is recommended for most productive applications, in order that several pages can use the same layout. We don't need to provide any version here, as they are part of the dependency management plugin of Spring Boot.

@Controller
@RequestMapping("/todo")
public class TodoController {

    // ...

    @GetMapping
    public String list(final Model model) {
        model.addAttribute("todos", todoService.findAll());
        return "todo/list";
    }

}

A simple MVC controller

Our simple endpoint just shows a list of todos. For this all current todos are loaded from the service first and added to the model. With "todo/list" the template from src/main/resources/templates/todo/list.html is loaded. Unless we configure it otherwise, the template folder is the default one from which the templates are picked.

<!DOCTYPE HTML>
<html xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
        layout:decorate="~{layout}">
    <head>
        <title>[[#{todoList.list.headline}]]</title>
    </head>
    <body>
        <div layout:fragment="content">
            <!-- ... -->
            <div th:if="${todoLists.empty}">[[#{todoList.list.empty}]]</div>
            <div th:if="${!todoLists.empty}" class="table-responsive">
                <table class="table table-striped table-hover align-middle">
                    <thead>
                        <tr>
                            <th scope="col">[[#{todoList.name.label}]]</th>
                            <th><!-- --></th>
                        </tr>
                    </thead>
                    <tbody>
                        <tr th:each="todo : ${todos}">
                            <td>[[${todo.name}]]</td>
                            <td>
                                <div class="float-end text-nowrap">
                                    <a th:href="@{/todos/edit/{id}(id=${todo.id})}" class="btn btn-sm btn-info">[[#{todo.list.edit}]]</a>
                                </div>
                            </td>
                        </tr>
                    </tbody>
                </table>
            </div>
        </div>
    </body>
</html>

A simple Thymeleaf Template

After adding our list.html template, we are already using Thymeleaf and Bootstrap classes successfully - the only missing layout will be shown in a moment. To enable real hot reloading during development, it is not enough to switch off template caching. How to read the HTML files directly from the file system is described in this article.

Bootstrap integration using WebJars

Bootstrap is currently the most popular CSS framework and can be integrated directly into our Spring Boot app using WebJars. For this we need another dependency first.

implementation('org.webjars:bootstrap:5.3.3')

We can now include the JavaScript and CSS files for Bootstrap in our layout.html as follows. Our own JS or CSS can be provided additionally in src/main/resources/static/js and src/main/resources/static/css if needed.

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org" xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
    <head>
        <!-- ... -->
        <link th:href="@{/webjars/bootstrap/5.3.0/css/bootstrap.min.css}" rel="stylesheet" />
        <link th:href="@{/css/app.css}" rel="stylesheet" />
        <script th:src="@{/webjars/bootstrap/5.3.0/js/bootstrap.bundle.min.js}" defer></script>
        <script th:src="@{/js/app.js}" defer></script>
    </head>
    <body>
        <main class="my-5">
            <div class="container">
                <!-- ... -->
                <div layout:fragment="content" />
            </div>
        </main>
    </body>
</html>

Integration of Bootstrap files in their minimized versions

Bootstrap integration using Webpack

Alternatively, Bootstrap can also be integrated using Webpack to define more complex rules for how CSS and JS should be provided to the frontend. If Webpack is already prepared, only one command is needed to add Bootstrap.

npm i --save bootstrap @popperjs/core

However, since the Webpack setup with npm and DevServer requires a lot of explanation, please check the article about the setup of Spring Boot with Webpack. Using Webpack offers many advantages - but also comes with the cost of a higher integration effort.

In the Free plan of Bootify, Spring Boot application including a frontend stack can be initialized - directly in the browser, without registration. Thymeleaf with Bootstrap is available there, either directly via WebJars or via Webpack.

» Start Project on Bootify.io

Uppercase table names in Spring Boot

Thomas — Mon, 25 Mar 2024 15:37:25 +0000

In Spring Boot / Hibernate, the table name is derived from the entity name. What must our naming strategy look like to translate all table names to uppercase?

Without further configuration, the physical name of the entity is converted to lowercase with underscores - so our class LineItem becomes the table line_item. We could try to store the adjusted name at each table with @Table(name = "LINE_ITEM") to overwrite the physical name - but would still need to change the naming strategy, because otherwise it would be changed back to lowercase after all.

Therefore the best approach is to provide the transformation for all table names with a dedicated naming strategy. Additional information within the @Table annotation is no longer necessary.

public class CamelCaseToUppercaseTablesNamingStrategy extends CamelCaseToUnderscoresNamingStrategy {

    private Identifier adjustName(final Identifier name) {
        if (name == null) {
            return null;
        }
        final String adjustedName = name.getText().toUpperCase();
        return new Identifier(adjustedName, true);
    }

    @Override
    public Identifier toPhysicalTableName(final Identifier name, final JdbcEnvironment context) {
        return adjustName(super.toPhysicalTableName(name, context));
    }

}

Customization of all table names using a custom naming strategy

Our naming strategy extends from CamelCaseToUnderscoresNamingStrategy so that all other methods (e.g. for the field names) still apply. The table name is first changed to lowercase with underscores, and then altered to uppercase in adjustName.

All adjusted identifiers are automatically created with quoted = true. This prevents the database from changing the table name and the name is taken over exactly. Finally only one entry in our application.yml / application.properties is missing.

spring.jpa.hibernate.naming.physical-strategy=io.bootify.my_app.config.CamelCaseToUppercaseTablesNamingStrategy

With this, Hibernate / Spring Data translates all physical names to uppercase with underscores. We could also override the toColumnTableName method if we also want to translate the field names as well. With a little adjustment, camel case would also be possible as output.

Bootify allows to create any custom database schema for your next Spring Boot application - directly in the browser, without registration. In the Professional plan, four additional Naming Strategies are available for selection and directly provide the configured, executable application.

» See Features and Pricing

How to create a Kotlin Multi-Module Project

Thomas — Fri, 17 Nov 2023 12:18:27 +0000

Spring Boot and Kotlin are a powerful combination for creating modern web applications. For Kotlin, we usually use Gradle with the Kotlin DSL developed for it. How can we turn such a project into a multi-module project?

Multi-module projects allow a monolith to be broken down into distinct modules without the need for the complex infrastructure required for microservices. The modules are not only separate folders similar to packages, but also form a dependency graph - thus circular connections are not possible. In the end, each module is compiled into a jar, and all jar's together form the executable Spring Boot fat jar.

The correct partitioning of the modules is crucial for an architecture that supports maintainability of the app and collaboration within the team in the long run. A few tips on this can be found in best practices for multi-module projects.

Splitting the classes and resources into the modules

We can create a simple Kotlin project in the current Spring Boot version 3.1.5 directly in the Bootify Builder. With open project we launch a project and select Kotlin as language. Gradle is already preset, and the database we can set to None for now. With this we can already explore and download the source code.

Initial version of the build.gradle.kts

Before we customize the build file, we first prepare the two modules kotlin-web and kotlin-base and create two folders with exactly these names. For the web module we move only the HomeController to the new path ./kotlin-web/src/main/kotlin/io/bootify/kotlin/controller. All other classes and resources are relevant for the whole application, so we move the whole src folder to ./kotlin-base.

include 'kotlin-base', 'kotlin-web'

Adding the new settings.gradle file

We also need a new file that provides a list of all our modules to Gradle. With this, the only thing missing at last is the customization of the build.gradle.kts.

Customizing the build file

First we prepare the plugins. The version of Kotlin should always be derived from the Spring Boot version, as this ensures the highest possible compatibility - the newest Kotlin version is not tested with Spring Boot yet. The allprojects part specifies a few global settings.

import io.spring.gradle.dependencymanagement.dsl.DependencyManagementExtension
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
import org.springframework.boot.gradle.dsl.SpringBootExtension
import org.springframework.boot.gradle.tasks.run.BootRun

buildscript {
    repositories {
        mavenCentral()
    }
}

plugins {
    id("org.springframework.boot") version "3.1.5" apply false
    id("io.spring.dependency-management") version "1.1.3" apply false

    kotlin("jvm") version "1.8.22" apply false
    kotlin("plugin.spring") version "1.8.22" apply false
}

allprojects {
    tasks.withType<JavaCompile> {
        sourceCompatibility = "17"
        targetCompatibility = "17"
    }

    tasks.withType<KotlinCompile> {
        kotlinOptions {
            freeCompilerArgs = listOf("-Xjsr305=strict")
            jvmTarget = "17"
        }
    }
}

First part of our extended build file

In the following, the prepared plugins are applied to all submodules. Some settings like the location of the Spring Boot BOM and the main class are specified as well.

subprojects {
    apply {
        plugin("java-library")
        plugin("io.spring.dependency-management")
        plugin("org.jetbrains.kotlin.jvm")
        plugin("org.jetbrains.kotlin.plugin.spring")
        plugin("org.springframework.boot")
    }

    tasks.withType<Test> {
        useJUnitPlatform()
    }

    repositories {
        mavenCentral()
    }

    the<DependencyManagementExtension>().apply {
        imports {
            mavenBom(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        }
    }

    extra.apply {
        set("projectName", "${extra.get("rootProjectName")}-$project.name")
    }

    configure<SpringBootExtension> {
        mainClass.set("io.bootify.kotlin.base.KotlinApplicationKt")
    }

    tasks.getByName<BootRun>("bootRun") {
        enabled = false
    }
}

Second part of our build file

In the last part we configure our actual modules. Here kotlin-base is referenced by kotlin-web. By integrating further depedencies as api in kotlin-base they are visible in kotlin-web as well. With implementation a depedency would be "invisible" within kotlin-web during development, even if eventually all dependencies end up together in the fat jar.

project(":kotlin-web") {
    apply {
        plugin("application")
    }

    tasks.getByName<BootRun>("bootRun") {
        environment.put("SPRING_PROFILES_ACTIVE", environment.get("SPRING_PROFILES_ACTIVE") ?: "local")
        workingDir = rootProject.projectDir
        enabled = true
    }

    dependencies {
        val api by configurations

        api(project(":kotlin-base"))
    }
}

project(":kotlin-base") {
    dependencies {
        val api by configurations

        api("org.springframework.boot:spring-boot-starter-web")
        api("org.springframework.boot:spring-boot-starter-validation")
        api("org.jetbrains.kotlin:kotlin-reflect")
        api("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
    }
}

Last part of our build file

The bootRun task is only enabled for our kotlin-web module and uses the root module as a working directory. This way all required files like docker-compose.yml can be picked up from there.

With this we have already transformed our project into a multi-module project! With gradlew clean build we can build our application as usual - which will compile and test each modules one after the other according to their dependency path.

Bootify offers an option in the Professional plan to create a multi-module project. This creates the structure described here, matching the other settings selected. In addition, integration tests are available and custom modules can be added, which are then already integrated into the build process.

» See Features and Pricing

Custom Template for your Spring Boot App

Thomas — Mon, 23 Oct 2023 15:54:54 +0000

Bootify is a tool for creating your individual template for a Spring Boot application. Numerous features are available, which are added to the template exactly as required.

Preferences and database schema

In the General Tab, general specifications can be made first: Java or Kotlin, enable Lombok, choose a frontend stack and a database, and so on. Select between technical or domain oriented package structure.

Choice of database and preferences

In the Entity tab the database schema for the selected database can then be created. This will generate the JPA / Hibernate entities with the annotations for fields and relations from the schema. If the CRUD option has been activated for the REST API or the frontend, additional services and controllers are available.

Editing an entity

With the Professional plan, extended features for your Spring Boot template are available. These include Spring Security (JWT, form-based login or Keycloak via OIDC), integration tests including Testcontainers, pagination and much more.

Customizable Templates in the DevOps Plan

In the DevOps plan the Bootify Builder itself can be customized. This allows to configure the options in such a way that the generated application always corresponds to the environment of the company. Any custom files can be added to the template. Special hooks are available to extend the build files at the required points.

With Bootify, the Developer Experience is in the focus: the created Spring Boot template saves a lot of time by providing components that are needed over and over again. At the same time, the code is free of external dependencies and avoids unnecessary overhead.

» See Features and Pricing

Using htmx with Spring Boot and Thymeleaf

Thomas — Tue, 15 Aug 2023 12:09:18 +0000

Htmx allows building complex web applications that feel like an SPA without relying on Angular or React. The client's behavior is mainly controlled by attributes within the HTML code that execute an Ajax request and integrate the result into the DOM - perfectly fitting for server-side rendering with Thymeleaf.

Basic setup

To keep the example simple, let's setup a Spring Boot application based on Thymeleaf and Bootstrap. We use WebJars to provide the libraries for the client.

dependencies {
    implementation('org.springframework.boot:spring-boot-starter-web')
    implementation('org.springframework.boot:spring-boot-starter-thymeleaf')
    implementation('org.webjars:bootstrap:5.3.1')
    implementation('org.webjars.npm:htmx.org:1.9.4')
    developmentOnly('org.springframework.boot:spring-boot-devtools')
}

Required dependencies for using Thymeleaf, Bootstrap and htmx

Our controller will render our index page and already contains a second endpoint for loading additional info via AJAX later on.

@Controller
public class HomeController {

    @GetMapping("/")
    public String index() {
        return "index";
    }

    @PostMapping("/furtherInfo")
    public String furtherInfo() {
        return "furtherInfo";
    }

}

Controller to output our templates

Let's prepare a simple template for our index page. We won't use a dedicated layout here.

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
    <head>
        <title>Homepage</title>
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <link th:href="@{/webjars/bootstrap/5.3.1/css/bootstrap.min.css}" rel="stylesheet" />
        <script th:src="@{/webjars/bootstrap/5.3.1/js/bootstrap.bundle.min.js}" defer></script>
        <script th:src="@{/webjars/htmx.org/1.9.4/dist/htmx.min.js}" defer></script>
    </head>
    <body>
        <main class="my-5">
            <div class="container">
                <h1 class="mb-4">Homepage</h1>
                <p class="mb-5 js-greeting">Hello World!</p>
                <button>Change greeting</button>
            </div>
        </main>
    </body>
</html>

Our Thymeleaf template in resources/templates/index.html

How we create ourselves a complete project is described further below. If everything is set up correctly, after starting the application we can reach our home page at http://loclahost:8080/.

Activate htmx behavior

Without further configuration htmx is not enabling any functionality. Let's quickly add some logic to our button, which will call the second endpoint of our controller and replace our greeting message.

<button th:hx-post="@{/furtherInfo}"
        hx-trigger="click"
        hx-target=".js-greeting"
        hx-swap="outerHTML">Change greeting</button>

Extend our button with htmx logic

We use Thymeleaf's ability here to populate any HTML attribute - in this case we create the link to our endpoint, which will be contained in the hx-post attribute. On click, htmx will now call the endpoint via Ajax and replace our targeted <p> element with the response. A more detailed explanation of the attributes can be found in the htmx documentation.

<p class="mb-5 js-greeting">Hello Pluto!</p>

Updated greeting in furtherInfo.html

Alternatively, we could add the hx-boost="true" attribute to our body element. This will cause all links and forms to be picked up by htmx, so all actions are performed without reloading the browser - creating an SPA-like user experience. Two possible approaches to error handling of htmx requests in Spring Boot are described in this article.

Generate propotype with htmx setup

With Bootify the described setup can be generated directly in the browser. The frontend with htmx is available in the Free plan without registration.

Options to generate a Spring Boot app with htmx

The current versions of all libraries are always used, and an individual database schema including CRUD functions can be added if required.

» Start Project on Bootify.io

Forem: Thomas

Spring Modulith vs Multi-Module projects - advantages and disadvantages

Spring Modulith and Multi-Module explained

Differences in practice

Choosing an approach

Integrate jte with Spring Boot

Application configuration

Layout and first pages

More complex setups

The JHipster alternative for modern Spring Boot apps

What are the advantages of Bootify over JHipster?

When should Bootify be chosen?

Integrating Spring Boot with Angular

Angular setup

Spring Boot integration

Htmx error handling in Spring Boot apps

Adding a dedicated error handling to our app

Error handling in the browser

Creating Test Jars in Maven for multi-module projects

Form Login with Spring Boot and Thymeleaf

Start with a simple application

Configuration of Spring Security

Loading users from our database

Add login controller

Starting our application

Spring Boot with Thymeleaf and Bootstrap

Adding Themeleaf to our app

Bootstrap integration using WebJars

Bootstrap integration using Webpack

Further readings

Uppercase table names in Spring Boot

How to create a Kotlin Multi-Module Project

Splitting the classes and resources into the modules

Customizing the build file

Custom Template for your Spring Boot App

Preferences and database schema

Customizable Templates in the DevOps Plan

Using htmx with Spring Boot and Thymeleaf

Basic setup

Activate htmx behavior

Generate propotype with htmx setup