In my previous post I showed how to use Preact Islands to handle the 5% of interactions where Alpine.js falls apart. Preact works great, but if you've ever looked at Svelte and thought "that looks cleaner" — you're right.

Svelte 5 with runes (\(state, \)props, $derived) is a natural fit for islands. No useSignalimport, no re-exporting render and h. The component syntax is just cleaner. And with Bun's plugin system, we compile .svelte files the same way we compiled .tsx — zero webpack, zero SPA router.

I migrated PhotoQuest from Preact to Svelte islands, and in this post I'll show you how to set up the same Kanban board example from the Preact article, but with Svelte 5 + Kotlin.

If you haven't read the Preact post, don't worry. This article is self-contained. But the Preact version is useful for comparison.

What Changes from Preact?

The architecture stays the same. Server renders HTML, passes JSON props, a mount script hydrates the island. What changes:

Architecture Overview

src/main/kotlin/de/tschuehly/svelte_islands_demo/web/kanban/
    KanbanComponent.kt                # Server-side ViewComponent + Controller
    KanbanComponent.html              # Thymeleaf template (thin shell)
    KanbanIsland.svelte               # Svelte 5 island (all client logic)
    KanbanIslandProps.ts              # TypeScript interface (auto-generated)
    KanbanService.kt                  # Board data service

src/main/kotlin/de/tschuehly/svelte_islands_demo/common/
    IslandTypeGenerator.kt            # Generates .ts from @Serializable classes

frontend/
    build.ts                         # Bun build script (with Svelte plugin)
    watch.ts                         # Dev file watcher
    bunfig.toml                      # Bun config (no JSX needed)
    tsconfig.json                    # TypeScript config

src/main/resources/static/js/
    mount.js                         # Island mount script (12 lines)
    islands/                         # Build output (gitignored)
        kanban/KanbanIsland.js

Same colocation principle: the .svelte file lives next to the ViewComponent it belongs to.

Setting Up Svelte Islands

Install Dependencies

// package.json
{
  "dependencies": {
    "svelte": "^5.50.2"
  }
}

That's it. No @preact/signals, no JSX import source. Just Svelte.

Configure Bun

Since we're not using JSX anymore, the config is minimal:

// frontend/tsconfig.json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "commonjs"
  }
}

No jsx, no jsxImportSource, no paths for module resolution. Svelte handles its own compilation.

The Build Script (with Svelte Plugin)

This is where the magic happens. Bun doesn't understand .svelte files natively, so we add a plugin that compiles them via svelte/compiler:

// frontend/build.ts
import {Glob} from "bun";
import {compile} from "svelte/compiler";
import type {BunPlugin} from "bun";

const sourceRoot = "../src/main/kotlin/de/tschuehly/svelte_islands_demo/web/";
const scanRoot = "../src/main/kotlin";

const sveltePlugin: BunPlugin = {
  name: "svelte",
  setup(build) {
    build.onLoad({filter: /\.svelte$/}, async (args) => {
      const source = await Bun.file(args.path).text();
      const result = compile(source, {
        filename: args.path,
        generate: "client",
        css: "injected",
      });
      return {
        contents: result.js.code,
        loader: "js",
      };
    });
  },
};

const glob = new Glob("**/*.svelte");
const entrypoints: string[] = [];

for await (const file of glob.scan(scanRoot)) {
  entrypoints.push(`\({scanRoot}/\){file}`);
}

console.log(`Found ${entrypoints.length} island(s):`);
entrypoints.forEach((e) => console.log(`  ${e}`));

await Bun.build({
  entrypoints,
  outdir: "../src/main/resources/static/js/islands",
  root: sourceRoot,
  minify: true,
  naming: "[dir]/[name].js",
  plugins: [sveltePlugin],
});

console.log("Build complete.");

In detail:

• sveltePlugin -> intercepts every .svelte file import and compiles it to JavaScript using svelte/compiler
• generate: "client" -> generates browser-ready code (not SSR)
• css: "injected" -> Svelte injects scoped CSS directly into the DOM at runtime. No separate CSS files needed
• The rest is identical to the Preact build: scan for entrypoints, output to islands/, mirror the package structure

The Mount Script

The mount script changes slightly. Instead of Preact's render(h()), we use Svelte's mount():

// src/main/resources/static/js/mount.js
document.querySelectorAll("[data-island]").forEach(async (el) => {
  const name = el.dataset.island;

  try {
    const props = JSON.parse(el.dataset.props || "{}");
    const {default: Component, mount} = await import(`/js/islands/${name}.js`);
    el.innerHTML = "";
    mount(Component, {target: el, props});
  } catch (err) {
    console.error(`Failed to mount island "${name}":`, err);
    el.innerHTML = '<div class="alert alert-error">Component could not be loaded.</div>';
  }
});

Important: Each Svelte island must re-export mount from svelte in a <script module> block:

<script module>
  export {mount} from 'svelte';
</script>

Why <script module>? This is Svelte 5's way of exporting things at the module level — code that runs once per import, not once per component instance. The mount function from Svelte is what creates and attaches a component to a DOM element. Since mount.js is a plain browser module that can't resolve bare 'svelte' imports, the island bundle must include it.

Include mount.js in Your Layout

<!-- LayoutViewComponent.html -->
<script th:src="@{/js/mount.js}" type="module"></script>

Same as the Preact version.

Writing the Svelte Island

Here's the kanban board as a Svelte 5 component. Compare this to the Preact version — no useSignal, no h(), no explicit re-renders:

<!-- src/main/kotlin/de/tschuehly/svelte_islands_demo/web/kanban/KanbanIsland.svelte -->
<script module>
  export {mount} from 'svelte';
</script>

<script lang="ts">
  import type {KanbanIslandProps, KanbanCard, KanbanColumn} from './KanbanIslandProps.ts';

  let {columns: initialColumns}: KanbanIslandProps = $props();

  let columns: KanbanColumn[] = $state(
      initialColumns.map(col => ({...col, cards: [...col.cards]}))
  );
  let nextId = $state(
      Math.max(...initialColumns.flatMap(c => c.cards.map(card => card.id)), 0) + 1
  );

  // Drag state
  let dragCardId: number | null = $state(null);
  let dragFromColumnId: string | null = $state(null);

  // Edit state — which card is being edited
  let editingCardId: number | null = $state(null);
  let editTitle = $state('');
  let editPriority = $state('medium');
  let editAssignee = $state('');

  // Add state — which column has the add form open
  let addingColumnId: string | null = $state(null);
  let newTitle = $state('');
  let newPriority = $state('medium');
  let newAssignee = $state('');

  function moveCard(cardId: number, fromColId: string, toColId: string) {
    const card = columns.find(c => c.id === fromColId)!.cards.find(c => c.id === cardId)!;
    columns = columns.map(col => {
      if (col.id === fromColId) return {...col, cards: col.cards.filter(c => c.id !== cardId)};
      if (col.id === toColId) return {...col, cards: [...col.cards, card]};
      return col;
    });
  }

  function deleteCard(colId: string, cardId: number) {
    columns = columns.map(col =>
        col.id === colId ? {...col, cards: col.cards.filter(c => c.id !== cardId)} : col
    );
  }

  function updateCard(colId: string, cardId: number, data: Partial<KanbanCard>) {
    columns = columns.map(col =>
        col.id === colId
            ? {...col, cards: col.cards.map(c => c.id === cardId ? {...c, ...data} : c)}
            : col
    );
  }

  function addCard(colId: string, data: Omit<KanbanCard, 'id'>) {
    const id = nextId++;
    columns = columns.map(col =>
        col.id === colId ? {...col, cards: [...col.cards, {id, ...data}]} : col
    );
  }

  function startEdit(card: KanbanCard) {
    editingCardId = card.id;
    editTitle = card.title;
    editPriority = card.priority;
    editAssignee = card.assignee;
  }

  function saveEdit(colId: string) {
    if (editingCardId == null) return;
    updateCard(colId, editingCardId, {
      title: editTitle,
      priority: editPriority,
      assignee: editAssignee
    });
    editingCardId = null;
  }

  function startAdd(colId: string) {
    addingColumnId = colId;
    newTitle = '';
    newPriority = 'medium';
    newAssignee = '';
  }

  function saveAdd() {
    if (addingColumnId == null) return;
    addCard(addingColumnId, {
      title: newTitle,
      priority: newPriority,
      assignee: newAssignee
    });
    addingColumnId = null;
  }
</script>

<div class="flex gap-4 overflow-x-auto p-4">
  {#each columns as column (column.id)}
    <div
        class="w-72 rounded-lg p-3 bg-base-200"
        ondragover={(e) => { e.preventDefault(); }}
        ondrop={() => {
          if (dragCardId && dragFromColumnId !== column.id) {
            moveCard(dragCardId, dragFromColumnId, column.id);
          }
        }}
    >
      <div class="flex justify-between items-center mb-3">
        <h3 class="font-bold">{column.title}</h3>
        <span class="badge badge-ghost badge-sm">{column.cards.length}</span>
      </div>

      {#each column.cards as card (card.id)}
        <div
            class="bg-base-100 rounded-lg p-3 mb-2 shadow-sm cursor-grab"
            draggable="true"
            ondragstart={() => { dragCardId = card.id; dragFromColumnId = column.id; }}
            ondragend={() => { dragCardId = null; dragFromColumnId = null; }}
        >
          {#if editingCardId === card.id}
            <div class="space-y-2">
              <input class="input input-sm w-full" bind:value={editTitle} />
              <select class="select select-sm w-full" bind:value={editPriority}>
                <option value="low">Low</option>
                <option value="medium">Medium</option>
                <option value="high">High</option>
              </select>
              <input class="input input-sm w-full" bind:value={editAssignee}
                     placeholder="Assignee" />
              <div class="flex gap-1">
                <button class="btn btn-xs btn-primary" onclick={() => saveEdit(column.id)}>
                  Save
                </button>
                <button class="btn btn-xs" onclick={() => { editingCardId = null; }}>
                  Cancel
                </button>
              </div>
            </div>
          {:else}
            <div>
              <div class="flex justify-between items-start">
                <span class="font-medium">{card.title}</span>
                <span class="badge badge-sm {
                  card.priority === 'high' ? 'badge-error' :
                  card.priority === 'medium' ? 'badge-warning' : 'badge-info'
                }">{card.priority}</span>
              </div>
              <div class="text-sm text-base-content/60 mt-1">{card.assignee}</div>
              <div class="flex gap-1 mt-2">
                <button class="btn btn-xs" onclick={() => startEdit(card)}>Edit</button>
                <button class="btn btn-xs btn-error"
                        onclick={() => deleteCard(column.id, card.id)}>Delete</button>
              </div>
            </div>
          {/if}
        </div>
      {/each}

      {#if addingColumnId === column.id}
        <div class="bg-base-100 rounded-lg p-3 mb-2 space-y-2">
          <input class="input input-sm w-full" bind:value={newTitle}
                 placeholder="Card title" />
          <select class="select select-sm w-full" bind:value={newPriority}>
            <option value="low">Low</option>
            <option value="medium">Medium</option>
            <option value="high">High</option>
          </select>
          <input class="input input-sm w-full" bind:value={newAssignee}
                 placeholder="Assignee" />
          <div class="flex gap-1">
            <button class="btn btn-xs btn-primary" onclick={saveAdd}>Add</button>
            <button class="btn btn-xs" onclick={() => { addingColumnId = null; }}>
              Cancel
            </button>
          </div>
        </div>
      {:else}
        <button class="btn btn-sm btn-ghost w-full mt-2"
                onclick={() => startAdd(column.id)}>+ Add Card</button>
      {/if}
    </div>
  {/each}
</div>

Compare this to the Preact version:

• $state() instead of useSignal() -> same reactivity, but it looks like regular JavaScript. No .value on read, Svelte's compiler handles that.
• $props() instead of function parameters -> destructured directly, type-safe via the imported interface
• {#each} with keyed blocks -> Svelte's template syntax replaces .map() with JSX
• bind:value -> two-way binding built into the language. No onInput handlers needed.
• <script module> -> exports mount once at module level, no need to re-export render and h
• css: "injected" -> if you add <style> blocks, Svelte scopes them to the component automatically
• UI state as $state variables -> editing and adding state tracked at component level (editingCardId, addingColumnId), with helper functions like startEdit() and saveEdit() to manage transitions

Wiring the Server Side (Kotlin)

The ViewComponent

Same pattern as the Java version, but with Kotlin data classes and Spring ViewComponent:

// KanbanComponent.kt
@ViewComponent
@Controller
class KanbanComponent(
    private val objectMapper: ObjectMapper,
    private val kanbanService: KanbanService,
    private val layoutViewComponent: LayoutViewComponent
) {

    @Serializable
    data class KanbanCard(val id: Int, val title: String, val priority: String, val assignee: String)

    @Serializable
    data class KanbanColumn(val id: String, val title: String, val cards: List<KanbanCard>)

    @Serializable
    data class KanbanIslandProps(val columns: List<KanbanColumn>)

    data class KanbanView(val islandPropsJson: String) : ViewContext

    @GetMapping("/")
    fun index(): ViewContext = layoutViewComponent.render(render())

    fun render(): KanbanView {
        val columns = kanbanService.getColumns()
        val islandProps = KanbanIslandProps(columns)
        return KanbanView(objectMapper.writeValueAsString(islandProps))
    }
}

In detail:

• Kotlin data classes serialize to JSON with Jackson out of the box — same as Java records but with less boilerplate
• @Serializable -> marks the class for kotlinx.serialization. This is what the IslandTypeGenerator uses to produce TypeScript interfaces automatically
• KanbanCard and KanbanColumn are the single source of truth — the TypeScript types are generated from them, not manually maintained
• The objectMapper.writeValueAsString() call turns the props into JSON that gets injected into data-props

The KanbanService

// KanbanService.kt
@Service
class KanbanService {

    fun getColumns(): List<KanbanComponent.KanbanColumn> = listOf(
        KanbanComponent.KanbanColumn(
            "todo", "To Do", listOf(
                KanbanComponent.KanbanCard(1, "Design landing page", "high", "Alice"),
                KanbanComponent.KanbanCard(2, "Write API docs", "medium", "Bob"),
            )
        ),
        KanbanComponent.KanbanColumn(
            "progress", "In Progress", listOf(
                KanbanComponent.KanbanCard(3, "Auth flow", "high", "Charlie"),
            )
        ),
        KanbanComponent.KanbanColumn("done", "Done", listOf()),
    )
}

The Thymeleaf Template

Identical to the Preact version. The template doesn't care what framework the island uses:

<!-- KanbanComponent.html -->
<!--/*@thymesVar id="kanbanView" type="de.tschuehly.svelte_islands_demo.web.kanban.KanbanComponent.KanbanView"*/-->

<div class="px-6 py-4">
  <!-- Svelte Island mounts here -->
  <div data-island="kanban/KanbanIsland"
       th:data-props="${kanbanView.islandPropsJson}">
    <span class="loading loading-spinner loading-lg"></span>
  </div>
</div>

Type-Safe Island Props (Auto-Generated)

In the Preact version, we manually maintained a .d.ts file that mirrored the Java records. That works, but it's one more thing that can drift out of sync. With Kotlin, we can do better.

The IslandTypeGenerator scans for any class ending in IslandProps that's annotated with @Serializable, and generates the TypeScript interface automatically using kxs-ts-gen:

// IslandTypeGenerator.kt
package de.tschuehly.svelte_islands_demo.common

import dev.adamko.kxstsgen.KxsTsGenerator
import kotlinx.serialization.InternalSerializationApi
import kotlinx.serialization.serializer
import java.io.File

@OptIn(InternalSerializationApi::class)
fun main() {
    val tsGenerator = KxsTsGenerator()
    val classesDir = File("build/classes/kotlin/main")
    val basePackage = "de/tschuehly/svelte_islands_demo"

    val islandPropsFiles = classesDir.resolve(basePackage)
        .walk()
        .filter { it.isFile && it.name.endsWith("IslandProps.class") }
        .toList()

    var count = 0
    for (classFile in islandPropsFiles) {
        val className = classFile.relativeTo(classesDir).path
            .removeSuffix(".class")
            .replace(File.separatorChar, '.')
        val clazz = Class.forName(className)
        val serializer = clazz.kotlin.serializer()
        val tsContent = tsGenerator.generate(serializer)

        val packagePath = clazz.`package`.name.replace('.', '/')
        val outputFile = File("src/main/kotlin/\(packagePath/\){clazz.simpleName}.ts")
        outputFile.writeText(buildString {
            appendLine("// Auto-generated by IslandTypeGenerator — do not edit")
            appendLine()
            appendLine(tsContent)
        })
        println("Generated ${outputFile.path}")
        count++
    }
    println("Generated $count island type definition(s)")
}

In detail:

• KxsTsGenerator -> converts kotlinx.serialization descriptors to TypeScript interfaces
• The walker scans compiled classes for anything ending in IslandProps.class — this also matches inner classes like KanbanComponent$KanbanIslandProps.class, which is exactly what we want since the props are nested inside the ViewComponent
• clazz.kotlin.serializer() -> gets the serializer that @Serializable generated at compile time
• The output .ts file is written next to the Kotlin source — same colocation principle as the .svelte files
• The // Auto-generated header makes it clear this file shouldn't be hand-edited

Running ./gradlew generateIslandTypes produces this file:

// KanbanIslandProps.ts
// Auto-generated by IslandTypeGenerator — do not edit

export interface KanbanCard {
  id: number;
  title: string;
  priority: string;
  assignee: string;
}

export interface KanbanColumn {
  id: string;
  title: string;
  cards: KanbanCard[];
}

export interface KanbanIslandProps {
  columns: KanbanColumn[];
}

No manual syncing. Add a field to the Kotlin data class, run the build, and the TypeScript interface updates automatically. The Svelte component imports it the same way:

<script lang="ts">
  import type {KanbanIslandProps, KanbanCard, KanbanColumn} from './KanbanIslandProps.ts';
</script>

You need two dependencies in your build.gradle.kts for this to work:

// build.gradle.kts (dependencies block)
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3")
implementation("dev.adamko.kxstsgen:kxs-ts-gen-core:0.2.1")

And the kotlinx.serialization Gradle plugin:

// build.gradle.kts (plugins block)
plugins {
    kotlin("plugin.serialization") version "2.1.0"
}

Gradle Integration

The Gradle tasks are nearly identical to the Preact version — swap .tsx for .svelte and add the type generation step:

// build.gradle.kts
val bunBinary: String = System.getenv("BUN_INSTALL")?.let { "$it/bin/bun" }
    ?: "${System.getProperty("user.home")}/.bun/bin/bun"

tasks.register<Exec>("bunInstall") {
    commandLine(bunBinary, "install")
}

tasks.register<JavaExec>("generateIslandTypes") {
    dependsOn("compileKotlin")
    mainClass.set("de.tschuehly.svelte_islands_demo.common.IslandTypeGeneratorKt")
    classpath = files(
        tasks.named("compileKotlin").map { it.outputs.files },
        sourceSets["main"].compileClasspath
    )
}

tasks.register<Exec>("bunBuild") {
    dependsOn("bunInstall", "generateIslandTypes")
    workingDir = file("frontend")
    commandLine(bunBinary, "run", "build.ts")
    inputs.files(fileTree("src/main/kotlin").matching { include("**/*.svelte") })
    inputs.file("frontend/build.ts")
    outputs.dir("src/main/resources/static/js/islands")
}

tasks.register<Exec>("bunWatch") {
    dependsOn("bunInstall")
    workingDir = file("frontend")
    commandLine(bunBinary, "run", "watch.ts")
}

tasks.named<ProcessResources>("processResources") {
    dependsOn("bunBuild")
}

In detail:

• generateIslandTypes -> compiles Kotlin first, then runs the IslandTypeGenerator against the compiled classes. This generates the .ts files before Bun tries to build the islands
• bunBuild depends on both bunInstall and generateIslandTypes -> so the TypeScript interfaces are always up-to-date when Bun compiles the .svelte files
• The inputs.files pattern uses **/*.svelte so Gradle knows when to re-run the build

Live Reload in Development

The Watch Script

Same approach as Preact, watching for .svelte changes:

// frontend/watch.ts
import {watch} from "fs";
import {resolve} from "path";

const scanRoot = resolve(import.meta.dir, "../src/main/kotlin");

async function build() {
  const proc = Bun.spawn(["bun", "run", "build.ts"], {
    cwd: import.meta.dir,
    stdout: "inherit",
    stderr: "inherit",
  });
  await proc.exited;
}

await build();

console.log(`Watching ${scanRoot} for .svelte changes...`);

let debounce: Timer | null = null;
watch(scanRoot, {recursive: true}, (event, filename) => {
  if (!filename?.endsWith(".svelte")) return;
  if (debounce) clearTimeout(debounce);
  debounce = setTimeout(async () => {
    console.log(`\n${filename} changed, rebuilding...`);
    await build();
  }, 200);
});

Spring Boot DevTools Integration (Kotlin)

The LiveReload config in Kotlin, excluding .svelte from triggering app restarts:

// IslandLiveReloadConfig.kt
@Configuration
@Profile("dev")
@ConditionalOnClass(FileSystemWatcher::class)
@EnableConfigurationProperties(DevToolsProperties::class)
class IslandLiveReloadConfig {

    private val logger = LoggerFactory.getLogger(IslandLiveReloadConfig::class.java)

    @Bean
    @RestartScope
    fun liveReloadServer(properties: DevToolsProperties): LiveReloadServer {
        return object : LiveReloadServer(
            properties.livereload.port,
            Restarter.getInstance().threadFactory
        ) {
            @Volatile
            private var lastReloadTime = 0L

            override fun triggerReload() {
                val now = System.currentTimeMillis()
                if (now - lastReloadTime < 3000) {
                    logger.debug("Debounced duplicate livereload")
                    return
                }
                lastReloadTime = now
                super.triggerReload()
            }
        }
    }

    @Bean
    fun islandFileSystemWatcher(liveReloadServer: LiveReloadServer): FileSystemWatcher {
        val watcher = FileSystemWatcher()
        val islandsDir = File("src/main/resources/static/js/islands")
        watcher.addSourceDirectory(islandsDir)
        watcher.addListener { changeSet ->
            if (changeSet.any { cf -> cf.files.any { it.relativeName.endsWith(".js") } }) {
                liveReloadServer.triggerReload()
            }
        }
        watcher.start()
        return watcher
    }

    @Bean
    fun classPathRestartStrategy(properties: DevToolsProperties): ClassPathRestartStrategy {
        val delegate = PatternClassPathRestartStrategy(properties.restart.allExclude)
        return ClassPathRestartStrategy { changedFile ->
            if (changedFile.relativeName.endsWith(".svelte")) false
            else delegate.isRestartRequired(changedFile)
        }
    }
}

Why Svelte over Preact?

Both work great for islands. Choose based on preference:

I personally switched PhotoQuest to Svelte because $state reads cleaner than useSignal() and the built-in CSS scoping is a nice bonus for islands that need custom styling.

When to Use What

Same as before. The three coexist perfectly. HTMX handles 90% of interactions. Alpine.js handles UI toggles. Svelte Islands handle the 5% where you need real component state and composability.

Summary

The architecture is identical: server renders HTML, passes typed JSON props, a 12-line mount script hydrates the island. The only difference is which frontend framework does the client-side rendering — and with the IslandTypeGenerator, the TypeScript interfaces stay in sync with your Kotlin data classes automatically. Pick whichever syntax you prefer.

If you want to learn more about HTMX + Spring Boot check out my HTMX + Spring Boot series. My side business PhotoQuest is built with Svelte islands + Kotlin + Spring Boot — exactly this stack.

If you have questions, ping me on twitter.com/tschuehly!

This is a known issue that affects every Java/Kotlin project on Claude Code Web. I wrote a Claude Code Hook that fixes it.

The Problem

When you run ./gradlew in a Claude Code Web session, Java tries to resolve services.gradle.org directly - bypassing the sandbox proxy entirely. You get this:

Exception in thread "main" java.net.UnknownHostException: services.gradle.org
    at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:567)
    ...
    at org.gradle.wrapper.GradleWrapperMain.main(SourceFile:67)

The frustrating part: curl downloads the exact same URL just fine because it honors https_proxy. The sandbox network works, Java just doesn't know about it.

The Fix: A PreToolUse Hook

Claude Code Hooks let you run shell scripts before or after specific tool invocations. We can use a PreToolUse hook on the Bash tool to configure the proxy before any command runs.

Let's first look at the full hook script:

#!/bin/bash
set -euo pipefail

# Only run in remote (Claude Code on the web) environments
if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
  exit 0
fi

# Configure Gradle proxy so Java can resolve external hosts
if [ -n "${https_proxy:-}" ]; then
  PROXY_HOST=$(echo "$https_proxy" | sed 's|.*@||' | sed 's|:.*||')
  PROXY_PORT=$(echo "$https_proxy" | sed 's|.*:||')
  PROXY_USER=$(echo "$https_proxy" | sed 's|http://||' | sed 's|@.*||' | sed 's|:.*||')
  PROXY_PASS=$(echo "$https_proxy" | sed 's|http://||' | sed 's|@.*||' | sed 's|^[^:]*:||')

  mkdir -p ~/.gradle
  cat > ~/.gradle/gradle.properties << PROPEOF
systemProp.http.proxyHost=$PROXY_HOST
systemProp.http.proxyPort=$PROXY_PORT
systemProp.http.proxyUser=$PROXY_USER
systemProp.http.proxyPassword=$PROXY_PASS
systemProp.https.proxyHost=$PROXY_HOST
systemProp.https.proxyPort=$PROXY_PORT
systemProp.https.proxyUser=$PROXY_USER
systemProp.https.proxyPassword=$PROXY_PASS
systemProp.jdk.http.auth.tunneling.disabledSchemes=
systemProp.jdk.http.auth.proxying.disabledSchemes=
PROPEOF
fi

# Download Gradle distribution if not already cached
cd "$CLAUDE_PROJECT_DIR"
./gradlew --version > /dev/null 2>&1

# Warm Gradle dependency cache
./gradlew compileKotlin compileTestKotlin --no-daemon 2>/dev/null || true

In detail:

• CLAUDE_CODE_REMOTE -> environment variable that's only set in Claude Code Web sessions, so the hook is a no-op locally
• We parse the https_proxy URL (format: http://user:pass@host:port) into its components using sed
• ~/.gradle/gradle.properties -> where Gradle reads JVM proxy system properties from
• systemProp.http.proxyHost / systemProp.https.proxyHost -> tells Java's HTTP client to route through the sandbox proxy
• jdk.http.auth.tunneling.disabledSchemes= / jdk.http.auth.proxying.disabledSchemes= -> by default Java disables Basic auth for HTTPS proxies, we clear that restriction so proxy authentication works
• ./gradlew --version -> triggers the Gradle distribution download through the now-configured proxy
• ./gradlew compileKotlin compileTestKotlin -> warms the dependency cache so Claude doesn't wait for downloads mid-task

Setting Up the Hook

Add this to your project's .claude/settings.json:

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/bin/bash .claude/hooks/pre-tool-use.sh"
          }
        ]
      }
    ]
  }
}

Then place the script at .claude/hooks/pre-tool-use.sh in your project.

Why a Hook Instead of a CLAUDE.md Instruction?

You could write "always configure the Gradle proxy before running builds" in your CLAUDE.md, but:

1. Claude might forget or skip it
2. It wastes tokens re-explaining the setup every session
3. A hook is deterministic it runs every time, no LLM reasoning required

Hooks are the right tool when you need guaranteed, repeatable setup. Save CLAUDE.md for guidance that requires judgment.

The Result

With this hook in place, Claude Code Web sessions with Spring Boot / Kotlin projects just work. No more UnknownHostException, no more manually downloading Gradle distributions with curl, no more wasted context window explaining proxy configuration to the AI.

If you want to learn more about Claude Code check out my other post on how I used Claude Code to plan a complex security migration. My side business PhotoQuest is also built with Spring Boot + htmx and was the project where I first ran into this issue.

Questions? Ping me on twitter.com/tschuehly.

But then you hit that one feature – a kanban board with draggable cards, inline editing, cross-column state, and per-card interactions. And you're suddenly writing an entire application inside HTML attributes.

Preact Islands fix this without throwing away your server-rendered architecture. Drop a single .tsx file next to your ViewComponent, and it becomes a self-contained interactive widget. No webpack, no SPA router. 3KB of Preact and your component logic.

I personally use this pattern in PhotoQuest for the few components where HTMX + Alpine.js weren't cutting it. Let me show you how to set it up.

The Problem: JavaScript in HTML Attributes

Here's a kanban board in Alpine.js. Users drag cards between columns, edit cards inline, and add new ones:

<!-- KanbanComponent.html -->
<div x-data="{
    columns: [
        { id: 'todo', title: 'To Do', cards: [
            { id: 1, title: 'Design landing page', priority: 'high', assignee: 'Alice' },
            { id: 2, title: 'Write API docs', priority: 'medium', assignee: 'Bob' },
        ]},
        { id: 'progress', title: 'In Progress', cards: [
            { id: 3, title: 'Auth flow', priority: 'high', assignee: 'Charlie' },
        ]},
        { id: 'done', title: 'Done', cards: [] },
    ],
    dragCard: null,
    dragFromCol: null,
    editingCard: null,
    editForm: { title: '', priority: 'medium', assignee: '' },
    addingToCol: null,
    newCard: { title: '', priority: 'medium', assignee: '' },
    nextId: 4,
    startDrag(card, colId) { this.dragCard = card; this.dragFromCol = colId },
    onDrop(targetColId) {
        if (!this.dragCard || this.dragFromCol === targetColId) return;
        const from = this.columns.find(c => c.id === this.dragFromCol);
        const to = this.columns.find(c => c.id === targetColId);
        from.cards = from.cards.filter(c => c.id !== this.dragCard.id);
        to.cards.push(this.dragCard);
        this.dragCard = null; this.dragFromCol = null;
    },
    startEdit(card) {
        this.editingCard = card.id;
        this.editForm = { title: card.title, priority: card.priority, assignee: card.assignee };
    },
    saveEdit(colId) {
        const col = this.columns.find(c => c.id === colId);
        Object.assign(col.cards.find(c => c.id === this.editingCard), this.editForm);
        this.editingCard = null;
    },
    startAdd(colId) { this.addingToCol = colId; this.newCard = { title: '', priority: 'medium', assignee: '' } },
    confirmAdd() {
        this.columns.find(c => c.id === this.addingToCol).cards.push({ id: this.nextId++, ...this.newCard });
        this.addingToCol = null;
    },
    deleteCard(colId, cardId) {
        const col = this.columns.find(c => c.id === colId);
        col.cards = col.cards.filter(c => c.id !== cardId);
    },
    priorityColor(p) { return { high: 'badge-error', medium: 'badge-warning', low: 'badge-info' }[p] || '' }
}" class="flex gap-4">

  <template x-for="col in columns" :key="col.id">
    <div class="w-72 bg-base-200 rounded-lg p-3" @dragover.prevent @drop="onDrop(col.id)">
      <h3 x-text="col.title" class="font-bold mb-3"></h3>

      <template x-for="card in col.cards" :key="card.id">
        <div class="bg-base-100 rounded p-3 mb-2 cursor-grab"
             draggable="true" @dragstart="startDrag(card, col.id)">

          <template x-if="editingCard !== card.id">
            <div>
              <div class="flex justify-between">
                <span x-text="card.title" class="font-medium"></span>
                <span :class="'badge badge-sm ' + priorityColor(card.priority)"
                      x-text="card.priority"></span>
              </div>
              <div class="text-sm opacity-60 mt-1" x-text="card.assignee"></div>
              <div class="flex gap-1 mt-2">
                <button @click="startEdit(card)" class="btn btn-xs">Edit</button>
                <button @click="deleteCard(col.id, card.id)"
                        class="btn btn-xs btn-error">Delete
                </button>
              </div>
            </div>
          </template>

          <template x-if="editingCard === card.id">
            <div class="space-y-2">
              <input x-model="editForm.title" class="input input-sm w-full"/>
              <select x-model="editForm.priority" class="select select-sm w-full">
                <option value="low">Low</option>
                <option value="medium">Medium</option>
                <option value="high">High</option>
              </select>
              <input x-model="editForm.assignee" class="input input-sm w-full"
                     placeholder="Assignee"/>
              <div class="flex gap-1">
                <button @click="saveEdit(col.id)" class="btn btn-xs btn-primary">Save</button>
                <button @click="editingCard = null" class="btn btn-xs">Cancel</button>
              </div>
            </div>
          </template>
        </div>
      </template>

      <template x-if="addingToCol === col.id">
        <div class="bg-base-100 rounded p-3 mb-2 space-y-2">
          <input x-model="newCard.title" class="input input-sm w-full" placeholder="Card title"/>
          <select x-model="newCard.priority" class="select select-sm w-full">
            <option value="low">Low</option>
            <option value="medium">Medium</option>
            <option value="high">High</option>
          </select>
          <input x-model="newCard.assignee" class="input input-sm w-full" placeholder="Assignee"/>
          <div class="flex gap-1">
            <button @click="confirmAdd()" class="btn btn-xs btn-primary">Add</button>
            <button @click="addingToCol = null" class="btn btn-xs">Cancel</button>
          </div>
        </div>
      </template>

      <button @click="startAdd(col.id)" class="btn btn-sm btn-ghost w-full mt-2">+ Add Card</button>
    </div>
  </template>
</div>

This technically works. But look at what we're dealing with:

• One shared editForm and editingCard -> only one card can be edited at a time, and the state lives far from the card it belongs to

• Six methods that all find columns by ID with .find() -> duplicated lookup logic everywhere

• Drag state as two top-level variables -> dragCard and dragFromCol are global to the entire board

• Nested x-for + x-if -> the template is 80+ lines of interleaved logic and markup with no way to extract reusable pieces

• No syntax highlighting inside those HTML attributes, no IntelliJ autocomplete, no type safety

The Solution: Preact Islands

1. Place a .tsx file next to your ViewComponent

2. Bun compiles it to a JS bundle in static/js/islands/

3. A 12-line mount.js script finds [data-island] elements and mounts the Preact component

4. The server passes typed props as JSON via data-props

Architecture Overview

src/main/java/de/tschuehly/preact_islands_demo/web/kanban/
    KanbanComponent.java              # Server-side ViewComponent + Controller
    KanbanComponent.html              # Thymeleaf template (thin shell)
    KanbanIsland.tsx                   # Preact island (all client logic)
    KanbanIslandProps.d.ts             # TypeScript interface (manually maintained)
    KanbanService.java                 # Board data service

frontend/
    build.ts                         # Bun build script
    watch.ts                         # Dev file watcher
    bunfig.toml                      # JSX config
    tsconfig.json                    # TypeScript config

src/main/resources/static/js/
    mount.js                         # Island mount script (12 lines)
    islands/                         # Build output (gitignored)
        kanban/KanbanIsland.js

The .tsx lives next to the ViewComponent it belongs to, in the same package directory. Not in a separate frontend/src/components/ directory three folders away.

Setting Up Preact Islands

Install Dependencies

Add preact to your root package.json so IntelliJ resolves the imports properly:

// package.json
{
  "dependencies": {
    "preact": "^10.28.3",
    "@preact/signals": "^2.7.0"
  }
}

Configure Bun for Preact JSX

# frontend/bunfig.toml
[build]
jsx = "react-jsx"
jsxImportSource = "preact"

// frontend/tsconfig.json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "commonjs",
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
    "baseUrl": "..",
    "paths": {
      "preact": [
        "./node_modules/preact"
      ],
      "preact/*": [
        "./node_modules/preact/*"
      ]
    }
  }
}

The Build Script

frontend/build.ts scans for all .tsx files in the Java source tree and compiles them:

// frontend/build.ts
import {Glob} from "bun";

const sourceRoot = "../src/main/java/de/tschuehly/preact_islands_demo/web/";
const scanRoot = "../src/main/java";
const glob = new Glob("**/*.tsx");
const entrypoints: string[] = [];

for await (const file of glob.scan(scanRoot)) {
  entrypoints.push(`${scanRoot}/${file}`);
}

console.log(`Found ${entrypoints.length} island(s):`);
entrypoints.forEach((e) => console.log(`  ${e}`));

await Bun.build({
  entrypoints,
  outdir: "../src/main/resources/static/js/islands",
  root: sourceRoot,
  minify: true,
  naming: "[dir]/[name].js",
});

console.log("Build complete.");

In detail:

• root is set to sourceRoot -> the output directory structure mirrors the package structure

• naming: "[dir]/[name].js" -> a TSX file at web/kanban/KanbanIsland.tsx produces islands/kanban/KanbanIsland.js

• minify: true -> Bun tree-shakes and minifies everything in one pass

The Mount Script

This is the entire client-side runtime. 12 lines.

// src/main/resources/static/js/mount.js
document.querySelectorAll("[data-island]").forEach(async (el) => {
  const name = el.dataset.island;
  const props = JSON.parse(el.dataset.props || "{}");

  try {
    const {default: Component, render, h} = await import(`/js/islands/${name}.js`);
    el.innerHTML = "";
    render(h(Component, props), el);
  } catch (err) {
    console.error(`Failed to mount island "${name}":`, err);
    el.innerHTML = '<div class="alert alert-error">Component could not be loaded.</div>';
  }
});

It finds every [data-island] element, dynamically imports the JS bundle, and mounts it with the server-provided props. That's it.

Important: Each island TSX must re-export render and h:

export {render, h};

Why? mount.js is a plain browser JS module. It's not processed by Bun. It can't import { render, h } from "preact" because bare module specifiers don't resolve in the browser without an import map. Bun inlines Preact into each island bundle, so re-exporting from the island is how mount.js gets access.

Include mount.js in Your Layout

Add a single <script> tag to your layout template:

<!-- LayoutViewComponent.html -->
<script th:src="@{/js/mount.js}" type="module"></script>

type="module" ensures it runs after the DOM is ready and supports dynamic import().

Writing the Preact Island

Here's the same kanban board as composable Preact components:

// src/main/java/de/tschuehly/preact_islands_demo/web/kanban/KanbanIsland.tsx
import {render, h} from "preact";
import {useSignal, signal} from "@preact/signals";

export {render, h};

import type {KanbanIslandProps, KanbanCard, KanbanColumn} from "./KanbanIslandProps";

// --- Shared drag state (module-level signal) ---

const dragState = signal<{ cardId: number; fromColumnId: string } | null>(null);

// --- Sub-components ---

function PriorityBadge({priority}: { priority: string }) {
  const colors: Record<string, string> = {
    high: "badge-error", medium: "badge-warning", low: "badge-info",
  };
  return <span class={`badge badge-sm ${colors[priority] || ""}`}>{priority}</span>;
}

function Card({card, columnId, onDelete, onUpdate}: {
  card: KanbanCard;
  columnId: string;
  onDelete: (cardId: number) => void;
  onUpdate: (cardId: number, data: Partial<KanbanCard>) => void;
}) {
  const editing = useSignal(false);
  const title = useSignal(card.title);
  const priority = useSignal(card.priority);
  const assignee = useSignal(card.assignee);

  function save() {
    onUpdate(card.id, {title: title.value, priority: priority.value, assignee: assignee.value});
    editing.value = false;
  }

  return (
      <div class="bg-base-100 rounded-lg p-3 mb-2 shadow-sm cursor-grab"
           draggable
           onDragStart={() => {
             dragState.value = {cardId: card.id, fromColumnId: columnId}
           }}
           onDragEnd={() => {
             dragState.value = null
           }}>
        {editing.value ? (
            <div class="space-y-2">
              <input class="input input-sm w-full" value={title}
                     onInput={e => title.value = e.currentTarget.value}/>
              <select class="select select-sm w-full" value={priority}
                      onChange={e => priority.value = e.currentTarget.value}>
                <option value="low">Low</option>
                <option value="medium">Medium</option>
                <option value="high">High</option>
              </select>
              <input class="input input-sm w-full" value={assignee}
                     onInput={e => assignee.value = e.currentTarget.value} placeholder="Assignee"/>
              <div class="flex gap-1">
                <button class="btn btn-xs btn-primary" onClick={save}>Save</button>
                <button class="btn btn-xs" onClick={() => editing.value = false}>Cancel</button>
              </div>
            </div>
        ) : (
            <div>
              <div class="flex justify-between items-start">
                <span class="font-medium">{card.title}</span>
                <PriorityBadge priority={card.priority}/>
              </div>
              <div class="text-sm text-base-content/60 mt-1">{card.assignee}</div>
              <div class="flex gap-1 mt-2">
                <button class="btn btn-xs" onClick={() => editing.value = true}>Edit</button>
                <button class="btn btn-xs btn-error" onClick={() => onDelete(card.id)}>Delete</button>
              </div>
            </div>
        )}
      </div>
  );
}

function AddCardForm({onAdd, onCancel}: {
  onAdd: (data: Omit<KanbanCard, "id">) => void;
  onCancel: () => void;
}) {
  const title = useSignal("");
  const priority = useSignal("medium");
  const assignee = useSignal("");

  return (
      <div class="bg-base-100 rounded-lg p-3 mb-2 space-y-2">
        <input class="input input-sm w-full" value={title}
               onInput={e => title.value = e.currentTarget.value} placeholder="Card title"/>
        <select class="select select-sm w-full" value={priority}
                onChange={e => priority.value = e.currentTarget.value}>
          <option value="low">Low</option>
          <option value="medium">Medium</option>
          <option value="high">High</option>
        </select>
        <input class="input input-sm w-full" value={assignee}
               onInput={e => assignee.value = e.currentTarget.value} placeholder="Assignee"/>
        <div class="flex gap-1">
          <button class="btn btn-xs btn-primary" onClick={() => {
            onAdd({title: title.value, priority: priority.value, assignee: assignee.value});
          }}>Add
          </button>
          <button class="btn btn-xs" onClick={onCancel}>Cancel</button>
        </div>
      </div>
  );
}

function Column({column, onMove, onDelete, onUpdate, onAdd}: {
  column: KanbanColumn;
  onMove: (cardId: number, fromColId: string, toColId: string) => void;
  onDelete: (colId: string, cardId: number) => void;
  onUpdate: (colId: string, cardId: number, data: Partial<KanbanCard>) => void;
  onAdd: (colId: string, data: Omit<KanbanCard, "id">) => void;
}) {
  const adding = useSignal(false);
  const dragOver = useSignal(false);

  return (
      <div class={`w-72 rounded-lg p-3 ${dragOver.value ? "bg-primary/10" : "bg-base-200"}`}
           onDragOver={(e) => {
             e.preventDefault();
             dragOver.value = true
           }}
           onDragLeave={() => dragOver.value = false}
           onDrop={() => {
             dragOver.value = false;
             if (dragState.value && dragState.value.fromColumnId !== column.id) {
               onMove(dragState.value.cardId, dragState.value.fromColumnId, column.id);
             }
           }}>
        <div class="flex justify-between items-center mb-3">
          <h3 class="font-bold">{column.title}</h3>
          <span class="badge badge-ghost badge-sm">{column.cards.length}</span>
        </div>

        {column.cards.map(card => (
            <Card key={card.id} card={card} columnId={column.id}
                  onDelete={(cardId) => onDelete(column.id, cardId)}
                  onUpdate={(cardId, data) => onUpdate(column.id, cardId, data)}/>
        ))}

        {adding.value ? (
            <AddCardForm
                onAdd={(data) => {
                  onAdd(column.id, data);
                  adding.value = false
                }}
                onCancel={() => adding.value = false}/>
        ) : (
            <button class="btn btn-sm btn-ghost w-full mt-2"
                    onClick={() => adding.value = true}>+ Add Card</button>
        )}
      </div>
  );
}

// --- Main island component ---

export default function KanbanIsland({columns: initialColumns}: KanbanIslandProps) {
  const columns = useSignal(
      initialColumns.map(col => ({...col, cards: [...col.cards]}))
  );
  const nextId = useSignal(
      Math.max(...initialColumns.flatMap(c => c.cards.map(card => card.id)), 0) + 1
  );

  function moveCard(cardId: number, fromColId: string, toColId: string) {
    const prev = columns.value;
    const card = prev.find(c => c.id === fromColId)!.cards.find(c => c.id === cardId)!;
    columns.value = prev.map(col => {
      if (col.id === fromColId) return {...col, cards: col.cards.filter(c => c.id !== cardId)};
      if (col.id === toColId) return {...col, cards: [...col.cards, card]};
      return col;
    });
  }

  function deleteCard(colId: string, cardId: number) {
    columns.value = columns.value.map(col =>
        col.id === colId ? {...col, cards: col.cards.filter(c => c.id !== cardId)} : col
    );
  }

  function updateCard(colId: string, cardId: number, data: Partial<KanbanCard>) {
    columns.value = columns.value.map(col =>
        col.id === colId
            ? {...col, cards: col.cards.map(c => c.id === cardId ? {...c, ...data} : c)}
            : col
    );
  }

  function addCard(colId: string, data: Omit<KanbanCard, "id">) {
    const id = nextId.value++;
    columns.value = columns.value.map(col =>
        col.id === colId ? {...col, cards: [...col.cards, {id, ...data}]} : col
    );
  }

  return (
      <div class="flex gap-4 overflow-x-auto p-4">
        {columns.value.map(col => (
            <Column key={col.id} column={col}
                    onMove={moveCard} onDelete={deleteCard}
                    onUpdate={updateCard} onAdd={addCard}/>
        ))}
      </div>
  );
}

We went from one massive x-data block to five focused components:

• PriorityBadge -> tiny display component, reused in every card.

• Card -> owns its own edit state. Each card can be edited independently. No shared editingCard variable.

• AddCardForm -> owns its own form state. Each column gets its own form instance. No shared newCard + addingToCol.

• Column -> handles drag-over highlighting and composes cards + add form. The dragOver signal is local to each column.

• KanbanIsland -> board-level state and CRUD operations passed down as callbacks.

Wiring the Server Side

The ViewComponent

The ViewComponent prepares the props as JSON and passes them to the Thymeleaf template. We define the props as Java records these are the single source of truth that we mirror in the TypeScript interface.

// KanbanComponent.java
@ViewComponent
@Controller
public class KanbanComponent {

  private final ObjectMapper objectMapper;
  private final KanbanService kanbanService;
  private final LayoutViewComponent layoutViewComponent;

  public KanbanComponent(ObjectMapper objectMapper, KanbanService kanbanService,
      LayoutViewComponent layoutViewComponent) {
    this.objectMapper = objectMapper;
    this.kanbanService = kanbanService;
    this.layoutViewComponent = layoutViewComponent;
  }

  public record KanbanCard(int id, String title, String priority, String assignee) {}

  public record KanbanColumn(String id, String title, List<KanbanCard> cards) {}

  public record KanbanIslandProps(List<KanbanColumn> columns) {}

  public record KanbanView(String islandPropsJson) implements IViewContext {}

  @GetMapping("/")
  public IViewContext index() {
    return layoutViewComponent.render(render());
  }

  public KanbanView render() {
    var columns = kanbanService.getColumns();
    var islandProps = new KanbanIslandProps(columns);
    return new KanbanView(objectMapper.writeValueAsString(islandProps));
  }
}

In detail:

• @ViewComponent @Controller -> the component is both a Spring MVC controller and a ViewComponent. The @GetMapping handles the page route, render() builds the view context.

• Jackson automatically serializes Java records → no extra annotations needed

• KanbanCard and KanbanColumn are public nested records reused by both the service and the TypeScript interface

• The board data comes from a service → the server controls the initial state. The island handles all client-side interactions (drag, edit, add). You could add HTMX calls to persist changes back to the server.

The KanbanService

// KanbanService.java
@Service
public class KanbanService {

  public List<KanbanColumn> getColumns() {
    return List.of(
        new KanbanColumn("todo", "To Do", List.of(
            new KanbanCard(1, "Design landing page", "high", "Alice"),
            new KanbanCard(2, "Write API docs", "medium", "Bob")
        )),
        new KanbanColumn("progress", "In Progress", List.of(
            new KanbanCard(3, "Auth flow", "high", "Charlie")
        )),
        new KanbanColumn("done", "Done", List.of())
    );
  }
}

In a real app this would query a database. For our demo, hardcoded data is fine.

The Thymeleaf Template: Just a Shell

<!-- KanbanComponent.html -->
<!--/*@thymesVar id="kanbanView" type="de.tschuehly.preact_islands_demo.web.kanban.KanbanComponent.KanbanView"*/-->

<div class="px-6 py-4">
  <!-- Preact Island mounts here -->
  <div data-island="kanban/KanbanIsland"
       th:data-props="${kanbanView.islandPropsJson()}">
    <span class="loading loading-spinner loading-lg"></span>
  </div>
</div>

In detail:

• data-island="kanban/KanbanIsland" -> maps to the output path /js/islands/kanban/KanbanIsland.js

• th:data-props="${kanbanView.islandPropsJson()}" -> injects the server-side props as JSON

• The spinner inside the div is shown until Preact mounts and replaces the content, giving you a loading state for free

Type-Safe Island Props

The TypeScript interface mirrors the Java records and lives right next to the island:

// KanbanIslandProps.d.ts
export interface KanbanCard {
  id: number;
  title: string;
  priority: string;
  assignee: string;
}

export interface KanbanColumn {
  id: string;
  title: string;
  cards: KanbanCard[];
}

export interface KanbanIslandProps {
  columns: KanbanColumn[];
}

The TSX imports it with a simple relative path:

import type {KanbanIslandProps, KanbanCard, KanbanColumn} from "./KanbanIslandProps";

When you add or change a field on a Java record, update the .d.ts to match. With a handful of islands, this takes seconds. The Bun compiler catches any mismatch between the .d.ts and your TSX on the next build. You get a type error instead of a runtime surprise.

If you add a field to KanbanIslandProps or KanbanCard, the TSX compiler catches any missing props. Type safety from Java to TypeScript.

Gradle Integration

Let's wire everything into the build. Add these tasks to build.gradle.kts:

// build.gradle.kts
val bunBinary: String = System.getenv("BUN_INSTALL")?.let { "$it/bin/bun" }
    ?: "${System.getProperty("user.home")}/.bun/bin/bun"

tasks.register<Exec>("bunInstall") {
    commandLine(bunBinary, "install")
}

tasks.register<Exec>("bunBuild") {
    dependsOn("bunInstall")
    workingDir = file("frontend")
    commandLine(bunBinary, "run", "build.ts")
}

tasks.register<Exec>("bunWatch") {
    dependsOn("bunInstall")
    workingDir = file("frontend")
    commandLine(bunBinary, "run", "watch.ts")
}

tasks.named<ProcessResources>("processResources") {
    dependsOn("bunBuild")
}

Build chain: bunInstall -> bunBuild -> processResources.

In detail:

• bunInstall runs first -> ensures node_modules/ is up to date

• bunBuild compiles the TSX with the .d.ts files in place -> Bun's type checker catches mismatches between Java and TypeScript

• bunWatch is for development -> runs alongside Spring Boot

• processResources depends on bunBuild -> the compiled JS is in place before the app starts

.gitignore

Remember to gitignore the build artifacts:

/frontend/node_modules/
/src/main/resources/static/js/islands/

The compiled JS in islands/ is a build artifact. It gets regenerated on every build.

Live Reload in Development

For a great DX, we want TSX changes to appear in the browser instantly without restarting Spring Boot.

The Watch Script

frontend/watch.ts watches for .tsx changes and triggers a rebuild:

// frontend/watch.ts
import {watch} from "fs";
import {resolve} from "path";

const scanRoot = resolve(import.meta.dir, "../src/main/java");

async function build() {
  const proc = Bun.spawn(["bun", "run", "build.ts"], {
    cwd: import.meta.dir,
    stdout: "inherit",
    stderr: "inherit",
  });
  await proc.exited;
}

await build();

console.log(`Watching ${scanRoot} for .tsx changes...`);

let debounce: Timer | null = null;
watch(scanRoot, {recursive: true}, (event, filename) => {
  if (!filename?.endsWith(".tsx")) return;
  if (debounce) clearTimeout(debounce);
  debounce = setTimeout(async () => {
    console.log(`\n${filename} changed, rebuilding...`);
    await build();
  }, 200);
});

Run it alongside your Spring Boot app:

./gradlew bunWatch

Spring Boot DevTools Integration

The watch script rebuilds the JS, but the browser still needs to reload. Spring DevTools has a LiveReload server, but it needs to know about island changes. Also, .tsx files in the classpath must not trigger a full app restart, that would defeat the purpose.

// IslandLiveReloadConfig.java
@Configuration
@Profile("dev")
@ConditionalOnClass(FileSystemWatcher.class)
@EnableConfigurationProperties(DevToolsProperties.class)
public class IslandLiveReloadConfig {

  private static final Logger logger = LoggerFactory.getLogger(IslandLiveReloadConfig.class);

  /**
   * Debounced LiveReloadServer -- prevents double-reload when both
   * our island watcher and devtools classpath watcher fire.
   */
  @Bean
  @RestartScope
  LiveReloadServer liveReloadServer(DevToolsProperties properties) {
    return new LiveReloadServer(
        properties.getLivereload().getPort(),
        Restarter.getInstance().getThreadFactory()
    ) {
      private volatile long lastReloadTime = 0L;

      @Override
      public void triggerReload() {
        long now = System.currentTimeMillis();
        if (now - lastReloadTime < 3000) {
          logger.debug("Debounced duplicate livereload");
          return;
        }
        lastReloadTime = now;
        super.triggerReload();
      }
    };
  }

  /**
   * Watches bun build output for changes and triggers LiveReload.
   */
  @Bean
  FileSystemWatcher islandFileSystemWatcher(LiveReloadServer liveReloadServer) {
    var watcher = new FileSystemWatcher();
    var islandsDir = new File("src/main/resources/static/js/islands");
    watcher.addSourceDirectory(islandsDir);
    watcher.addListener(changeSet -> {
      boolean hasJs = changeSet.stream()
          .flatMap(cf -> cf.getFiles().stream())
          .anyMatch(f -> f.getRelativeName().endsWith(".js"));
      if (hasJs) {
        liveReloadServer.triggerReload();
      }
    });
    watcher.start();
    return watcher;
  }

  /**
   * Exclude .tsx from triggering a full app restart.
   */
  @Bean
  ClassPathRestartStrategy classPathRestartStrategy(DevToolsProperties properties) {
    var delegate = new PatternClassPathRestartStrategy(properties.getRestart().getAllExclude());
    return changedFile -> {
      if (changedFile.getRelativeName().endsWith(".tsx"))
        return false;
      return delegate.isRestartRequired(changedFile);
    };
  }
}

In detail:

• @RestartScope on the LiveReloadServer bean -> survives DevTools restarts, so we don't lose the debounce state

• islandFileSystemWatcher -> watches static/js/islands/ for new JS files and triggers LiveReload

• classPathRestartStrategy -> prevents .tsx files from triggering a full Spring Boot restart

This gives us a tight dev loop:

1. Edit a .tsx file in IntelliJ

2. bunWatch detects the change, rebuilds in ~50ms

3. The FileSystemWatcher sees new JS in static/js/islands/

4. LiveReload triggers a browser refresh

5. No Spring Boot restart required

How the Pieces Fit Together

  ┌──────────────────────┐
  │  Java records         │
  │  KanbanCard           │──── manually ────▶  KanbanIslandProps.d.ts
  │  KanbanColumn         │     mirrored        (TypeScript)
  │  KanbanIslandProps    │                        │
  └──────────┬────────────┘                        │
             │ ObjectMapper                        │ import type
  ┌──────────▼────────────┐                        │
  │   ViewComponent       │                        │
  │   objectMapper        │                        │
  │     .writeValueAsStr  │                        │
  └──────────┬────────────┘                        │
             │ data-props="{...}"                   │
  ┌──────────▼────────────┐                        │
  │   Thymeleaf Template  │                        │
  │   <div data-island=   │                        │
  │        data-props= /> │                        │
  └──────────┬────────────┘                        │
             │ HTML sent to browser                │
  ┌──────────▼────────────┐                        │
  │   mount.js            │                        │
  │   import → render     │                        │
  └──────────┬────────────┘                        │
             │                                     │
  ┌──────────▼────────────┐                        │
  │   Preact Island       │◀───────────────────────┘
  │   (.tsx)              │
  │   Composable pieces:  │
  │   Card                │
  │   Column              │
  │   AddCardForm         │
  └───────────────────────┘

Why Preact over React?

• 3KB gzipped vs React's 40KB+

• Same JSX/hooks API – your React knowledge transfers 1:1

• @preact/signals with useComputed is lighter and more ergonomic than useState + useMemo chains

• Bun builds a Preact island in ~50ms

When to Use What

The three coexist perfectly. HTMX handles 90% of interactions. Alpine.js handles UI toggles. Preact Islands handle the 5% of components where you need per-item component state, drag-and-drop, or deep composability with type safety.

Summary

The server controls the initial board state and passes it as typed JSON props, with the Java record as the single source of truth for the TypeScript interface. The rest of the page remains server-rendered with HTMX. Preact handles the interactive island. The same approach works with Svelte aswell.

If you want to learn more about HTMX + Spring Boot check out my HTMX + Spring Boot series. My side business PhotoQuest is also built with this exact stack.

If you have questions, ping me on twitter.com/tschuehly!

The result? ~700 lines of custom auth code eliminated.

But the real story isn't the code. It's how two conversations with Claude Code shaped the entire approach.

Planning complex migrations is one of those things developers usually do in their heads. We sketch something on a whiteboard, maybe write a few notes, then dive into code, and figure out the edge cases as we go. Claude Code can interview you about your architecture decisions and produce a comprehensive spec before you write a single line of code.

The First Conversation: Wrong Direction, Right Process

I started with a different goal. Every time I needed to get the current wedding/event, I was doing a 3-table join:

// EventService.kt
val event = sql.select()
    .from(EVENT)
    .join(EVENT_MEMBER).on(EVENT_MEMBER.EVENT_ID.eq(EVENT.ID))
    .join(WEBSITE_USER).on(WEBSITE_USER.SUPABASE_ID.eq(EVENT_MEMBER.SUPABASE_USER_ID))
    .where(WEBSITE_USER.SUPABASE_ID.eq(currentUserId))
    .fetchOne()

My idea: put event_id directly in the Supabase JWT. The query becomes a simple lookup:

// EventService.kt (refactored)
val event = sql.selectFrom(EVENT)
    .where(EVENT.ID.eq(eventIdFromJwt))
    .fetchOne()

Much cleaner, right?

Let's first ask Claude to interview me about this refactor:

Currently I implemented multiple users for one event via the event_member table.
I was thinking of refactoring this and putting the event_id in the JWT of the SupabaseUser.

Interview me in detail using the AskUserQuestionTool about literally anything:
technical implementation, UI & UX, concerns, tradeoffs, etc.

The key here is asking Claude to use the AskUserQuestionTool. This triggers an interactive interview mode where Claude asks you questions one by one, rather than making assumptions.

Claude produced a comprehensive spec and wrote it to docs/TODO/event-member-refactor-spec.md.

Summary of key decisions from interview:

Then I asked one question that changed everything:

Me: What if we moved away from Supabase Auth and just used Spring Security?

What followed was an interview that systematically explored every dimension of this alternative. Claude didn't just say yes or no. It asked questions that forced me to think through the implications.

The Systematic Interview

Claude started with the fundamentals:

Claude: What's driving the consideration to move away from Supabase Auth? Is it the complexity of JWT claim management we just discussed, or other factors?

My answer: "Want more control over auth flow."

Claude: Supabase Auth currently handles: anonymous sign-in, email magic links, OAuth (Google/Apple/Azure), email confirmation flow. Which of these do you actually need long-term?

My answer: "All of them I need feature parity."

This established the scope. Then Claude drilled into the technical tradeoffs:

Session vs JWT

Claude: For anonymous sign-in with Spring Security: this typically requires session-based auth (cookie), not JWT. Are you okay with session-based auth, or do you want stateless JWT throughout?

My answer: "Haven't thought about it, need guidance."

Claude: Session vs JWT tradeoff: Sessions are simpler (no refresh tokens, instant revocation, easy to store event_id), but require sticky sessions or shared session store for horizontal scaling. What's your current/planned deployment?

My answer: "Multiple instances, no shared store yet."

Claude: For multiple instances without a shared store: you'll need either Redis for sessions, or go stateless JWT. Redis adds infrastructure but simplifies auth. JWT adds token refresh complexity. Preference?

My answer: "Go JWT, accept refresh complexity."

This chain of questions narrowed down the architecture. Each answer constrained the next decision.

In detail:

• Session-based auth → simpler token management, but requires shared session store for scaling
• JWT → stateless and scales easily, but adds refresh token complexity
• I chose JWT because I didn't want to add Redis just for sessions

Anonymous User Flow

The anonymous→verified user flow was critical. Claude mapped it out:

Claude: Anonymous users are currently Supabase anonymous auth. With Spring Security, options: (A) guest session with upgrade path, (B) lazy account creation on first action, (C) require sign-up upfront. Which fits your UX?

My answer: "Keep current flow: anon -> email confirmation."

Claude: For anonymous->confirmed user flow with JWT: the anon user gets a JWT, then confirms email, and the JWT needs to be replaced with one containing their verified identity. How should this transition work?

My answer: "The Anon JWT needs to be long lived as I want the user to convert at a later date. What do you think?"

Claude: Long-lived anon JWT that converts: the cleanest approach is to keep the same user ID (UUID) throughout, just upgrade the 'verified' flag and add email claim on confirmation. The JWT gets replaced but user identity persists. Sound right?

My answer: "Yes, same user ID, upgrade claims."

Infrastructure Decisions

Claude systematically uncovered my infrastructure constraints:

Claude: Email magic links without Supabase means you need: email sending, token generation/validation, rate limiting. Do you have email infrastructure already (SES, Resend, etc.)?

My answer: "Yes, already using SES/similar."

Claude: Rate limiting and brute-force protection: Supabase handles this for you. With Spring Security, you'll need to implement it. Do you have rate limiting infrastructure (Redis, bucket4j, etc.)?

My answer: "No rate limiting infra yet."

Claude: For rate limiting without Redis: bucket4j can use JCache with local cache (Caffeine) for single-instance, , or PostgreSQL for distributed. Given your multi-instance setup, prefer DB-backed rate limiting or add Redis?

My answer: "DB-backed rate limiting (simpler infra)."

Each question built on the previous answer. The "no Redis" constraint shaped everything that followed.

The Tradeoff Explanations

When I needed guidance, Claude explained the options in detail:

Magic Link Token Storage

Claude: Let me explain the magic link token tradeoffs:

Option A: Dedicated table - Easy revocation, can track usage, simple expiry queries. Cons: DB write per request.

Option B: Stateless signed token - No DB storage, scales infinitely. Cons: Cannot revoke before expiry.

Option C: Hybrid - Fast validation (check signature first), DB only for revocation.

Recommendation: Given you want anon → confirmed conversion and might need to invalidate tokens, I'd lean toward Option A - the DB overhead is minimal for magic links (low volume).

CSRF Protection

Claude: Sec-Fetch-Site is a modern approach to CSRF protection. The header is browser-set (cannot be forged):

• same-origin: Request from your domain
• cross-site: Request from different domain

For CSRF protection, you'd reject state-changing requests where Sec-Fetch-Site: cross-site.

Pros: Simpler than CSRF tokens, no JS configuration needed for HTMX. Cons: Older browsers don't send it (Safari <16.4).

Recommendation: This works well for PhotoQuest since you target modern browsers (wedding guests with smartphones).

The Pivot Moment

After 14 tool calls and 6 messages, Claude had mapped out the entire architecture. I asked the final question:

Claude: Should this Spring Security migration be a separate spec, or should I update the existing event-member-refactor-spec to replace the Supabase JWT approach entirely?

My answer: "Combine into one comprehensive auth refactor spec."

Claude: Should I keep the phased approach where Supabase JWT refactor is Phase 1 (quick win), and Spring Security migration is Phase 2 (full control)? Or skip Supabase refactor entirely and go straight to Spring Security?

My answer: "Skip Supabase refactor, go straight to Spring."

Claude rewrote the entire spec. The original Supabase JWT approach was replaced with a comprehensive Spring Security migration. But I realized we'd only scratched the surface.

The Second Conversation: Deep-Dive Interview

The next day, I started fresh with the Spring Security spec. This time I wanted a thorough interview:

Read this @docs/TODO/supabase-auth-refactor-spec.md and interview me in detail
about literally anything: technical implementation, UI & UX, concerns, tradeoffs,
etc. but make sure the questions are not obvious - be very in-depth and continue
interviewing me continually until it's complete

Lookup Spring Security best practices: query-docs
/websites/spring_io_spring-security_reference_7_0 {query}

💡 I'm using the @ symbol to reference a file directly in the prompt. Claude Code will read the file and include it in context. The query-docs part tells Claude to look up Spring Security documentation as needed.

What followed: 15+ rounds of probing questions. Claude also looked up Spring Security 7 documentation in real-time. This meant the interview was grounded in current best practices, not outdated patterns from Stack Overflow circa 2019.

Here are some questions that forced me to think:

Session & Cookie Edge Cases

Claude: For Guest users with device cookies: What's the recovery strategy when a guest clears cookies mid-upload or switches devices?

My answer: Accept data loss. Guests must stay on one device. Simple beats complex.

Claude: Session timeout is 30 minutes. For wedding guests who might take photos over 3–4 hours, what's the acceptable re-auth UX?

My answer: Use persistent remember-me tokens. This led to adding persistent_logins table.

OAuth Provider Quirks

Claude: Apple OAuth may not return email on subsequent logins. How do we handle account linking when email is missing?

My answer: Require email on first Apple login only. Store in oauth_account.provider_email.

Security vs. UX Tradeoffs

Claude: If oneTimeTokenLogin validation fails (expired, invalid, already used), should we show specific error message or generic 'Invalid link'?

Security says generic. UX says specific. I chose specific: "Link expired", "Link already used". The attack surface is minimal.

Catching Claude's Confusion

The best moment: I caught Claude mixing concepts.

Claude: Anonymous user creation: When should anon users be created? On first visit, or only when they perform action?

My answer: "You are mixing guest and anon users. Anon users are brides trying the demo. Guests don't have an account."

This clarification became a table in the final spec:

Asking Claude for Recommendations

Claude: Integration tests should cover magic link + OAuth flows. For OAuth, should we mock provider responses or use Spring Security's OAuth2 test support?

My answer: "What would you recommend?"

Claude suggested Spring Security's built-in test support plus GreenMail for E2E magic link tests. Both made it into the spec.

The Output

Two conversations. 900-line specification. And we are done!

Here's what the final spec covered:

• Database migrations (6 tables: website_user, oauth_account, magic_link_token, device_cookie, persistent_logins, rate_limit_bucket)
• Complete SecurityConfig.kt with remember-me, CSRF, session fixation protection
• Unified PhotoQuestUser implementing both UserDetails and OAuth2User
• Account deletion service with ownership transfer checks
• Anonymous user cleanup job (7-day grace period)
• Data migration strategy with email normalization

Why This Works

Architecture exploration. The first conversation explored Supabase JWT claims in depth. This made the pivot question ("what about Spring Security?") more informed. Sometimes you need to plan the wrong thing to discover the right thing.

Rubber duck that asks questions. Claude forced me to articulate decisions I would have made implicitly – and probably inconsistently. Unlike a real rubber duck, this one pushes back.

Documentation as a side effect. The interview process produced a spec that's actually useful for implementation. No more "I'll document it later" (We all know how that ends).

Edge case discovery. Questions like "what if Apple OAuth doesn't return email?" aren't obvious when you're thinking about the happy path. Claude surfaces these before they become production bugs.

Try It Yourself

For your next complex feature or migration:

1. Write a rough spec or design doc
2. Ask Claude to interview you using AskUserQuestionTool
3. Be open to pivots – if Claude's questions reveal a better approach, explore it
4. Answer honestly – including "I don't know" or "what would you recommend?"
5. Let Claude write the updated spec

The interview format forces you to make decisions explicitly – rather than discovering them during implementation.

And sometimes the right question changes the entire direction.

If you want to learn more about building with Spring Security, HTMX, and server-side rendering, check out my HTMX + Spring Boot series. My side business PhotoQuest is also built entirely with this stack – no JavaScript framework headaches, just clean server-rendered HTML with htmx for interactivity.

If you have questions about using Claude Code for architecture planning, ping me on twitter.com/tschuehly!

Some of the features that are really nice to have:

• Continuous deployment using GitHub

• System Monitoring

• Paketo Buildpack support

• One Click Database deployment

• Automatic SSL certificates with LetsEncrypt

I personally use Hetzner for my VPS needs: Get 20€ credit in Hetzner-Cloud for free with this link!

Creating a Secure VPS on Hetzner

First we will need to create an ssh keypair: ssh-keygen -t ed25519

Then go to https://console.hetzner.cloud/projects and create a new VPS.

During the setup add this cloud-init script in the Cloud Config section. We need to replace YOUR_SSH_PUBLIC_KEY with the public key we just generated.

#cloud-config
users:
  - name: tschuehly
    groups: users, admin, docker
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash
    ssh_authorized_keys:
      - YOUR_SSH_PUBLIC_KEY
packages:
  - fail2ban
  - ufw
  - unattended-upgrades
package_update: true
package_upgrade: true
runcmd:
  - printf "[sshd]\nenabled = true\nbanaction = iptables-multiport" > /etc/fail2ban/jail.local
  - systemctl enable fail2ban
  - ufw allow OpenSSH
  - ufw enable
  - sed -i -e '/^\(#\|\)PermitRootLogin/s/^.*$/PermitRootLogin no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)PasswordAuthentication/s/^.*$/PasswordAuthentication no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)KbdInteractiveAuthentication/s/^.*$/KbdInteractiveAuthentication no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)ChallengeResponseAuthentication/s/^.*$/ChallengeResponseAuthentication no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)MaxAuthTries/s/^.*$/MaxAuthTries 2/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)AllowTcpForwarding/s/^.*$/AllowTcpForwarding no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)X11Forwarding/s/^.*$/X11Forwarding no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)AllowAgentForwarding/s/^.*$/AllowAgentForwarding no/' /etc/ssh/sshd_config
  - sed -i -e '/^\(#\|\)AuthorizedKeysFile/s/^.*$/AuthorizedKeysFile .ssh\/authorized_keys/' /etc/ssh/sshd_config
  - sed -i '$a AllowUsers tschuehly' /etc/ssh/sshd_config
  - reboot

Installing Dokploy

To install Dokploy, we need to ssh into the VPS, I personally use Termius as SSH client, but we can also use ssh directly:

ssh tschuehly@94.130.99.182

Then run this command to install Dokploy: `

curl -sSL https://dokploy.com/install.sh | sudo sh

After a few minutes we should see a success message:

We can now navigate to the dokploy instance and setup the admin account

Connect your GitHub Account

Now we need to connect our GitHub Account. Click on Settings, then on Git, then on GitHub and then Create GitHub App . Follow the Wizard and then click on Install App . Either give Dokploy access to all your repositories or only the one you want to deploy.

Deploy your Spring Application!

I will deploy my htmx-spring-workshop application. Let’s first create a new project!

Now we need to create a new application. Give it a name and then click on create!

We can now select the GitHub App, the repository, the branch and also the path of the Spring Application if your repository is a monorepo.

We will select Paketo Buildpacks, because friends don't let friends use Dockerfiles!

Before deploying we need to set the Java Version for the build process in the Environment Tab:

To configure a domain we can create a new DNS A record, it is possible to use a wildcard to only have to do it once.

Then we will configure the domain, and enable HTTPS with LetsEncrypt.

Finally we can click on deploy:

We can now see the progress of the deployment:

After a couple of minutes we can see that our application successfully started:

And we are finished! Our application is live! https://htmx.tschuehly.de/

If we now commit to the selected branch, the new application will automatically be rebuilt and redeployed.

Deploy a Database!

We can also easily deploy a Database like PostgreSQL.

Click on Create Service and then Database. Choose your favourite database and fill in the details.

You can then click on Deploy. All the details to connect to your database are listed:

We can then connect to the database with our Spring App by setting the environment variables:

And we are done!
We now have a SSL secured Spring Boot Application with a PostgreSQL database in production.

I deploy my own SaaS application this way: PhotoQuest

It compiles the templates into native java classes offering compile time safety. With hot reloading and the IntelliJ plugin it makes me really productive.

My tutorial Interactive web applications with htmx and Spring Boot gives a short introduction to JTE. My workshop Building server-side web applications with htmx also uses JTE.

After running my business for one year in production with Thymeleaf I recently decided to migrate to JTE as the developer experience is much better especially when refactoring model properties.

JTE is also one of the supported template languages of Spring ViewComponent

If you want to learn more about HTMX + Spring Boot check out my series Web development without the JavaScript headache with Spring + HTMX.

My side business PhotoQuest is also built with HTMX + JTE

Spring Boot developers usually build JSON APIs that get client-side rendered on the browser.

Marcus Hellberg tells us why we should aim to build a full-stack team:

But with the rise in complexity in modern JavaScript frameworks and the constant change it's hard to keep up!

The browser can only display HTML! Why send JSON to the client that needs to be rendered to HTML? We can just remove this unnecessary complexity!

We can render data directly into a HTML template on the server with an engine like JTE. We then return HTML to the browser directly.

But we lost the interactivity of the JavaScript framework. We can return it by leveraging Hypermedia.

Hypermedia Driven Applications

The core of a hypermedia driven application is hypertext. HTML defines how the application looks and how the user can interact with the application based on the current state of the application.

The underlying principle is "Hypermedia as Engine of Application State".

A simple example is an embedded form that returns a success message on successful submission:

We want a great user experience with our server-side rendered web application.

htmx

The htmx library enables modern UX that is comparable to a single page application.
htmx completes HTML as a hypertext and brings it to the 21st century.

The harsh reality is that HTML never got to the point that it could, by itself, offer UX approaching the thick client. Pure server-side rendered HTML offered only a simple & clunky Click → Request → Page Render model. For reasons I can’t completely understand, HTML never moved beyond this extremely basic UX model.

https://intercoolerjs.org/2020/01/14/taking-html-seriously

htmx enables interactivity by swapping parts of the DOM without reloading the page. It embeds hx attributes (application control information) in the HTML.

If you want to get an introduction to HTMX + Spring Boot:
Interactive web applications with htmx and Spring Boot

UI Components

Spring Boot is an awesome framework for building applications.
However, the traditional Spring MVC style lacks cohesion between the View (Templates) and the Model (Data).

The JavaScript frontend frameworks like React, Angular and Vue share one trait.
They build user interfaces with components. Components enable reusability and define a clear API.

In the Ruby and PHP communities, server-rendered UI components established themselves with Laravel Livewire and Rails ViewComponent

The main benefit is single responsibility:

ViewComponents consolidate the logic needed for a template into a single class, resulting in a cohesive object that is easy to understand

https://viewcomponent.org/#single-responsibility

With the open-source Spring ViewComponent library Spring Developers can enjoy the benefits of UI components.

Introducing Spring ViewComponent

A ViewComponent is a Spring managed bean. We can leverage backend patterns for UI composition.

We create a ViewComponent by annotating a class with the @ViewComponent annotation.

A ViewComponent class defines a rendering context for a corresponding template, this context is called ViewContext. We define a public nested record that implements the ViewContext interface.

SimpleViewComponent.java

@ViewComponent
public class SimpleViewComponent {
    public record SimpleViewContext(String helloWorld) implements ViewContext {
    }

    public SimpleView render() {
        return new SimpleView("Hello World");
    }
}

A ViewComponent needs to have a template with the same name defined in the same package.
In the template, we can access the fields of the ViewContext record.

SimpleViewComponent.jte

@param SimpleViewContext simpleViewContext
<p>
${simpleViewContext.helloWorld()}
</p>

To render the ViewComponent we inject it in the Controller and then call the render method in the endpoint mapping and return the ViewContext result:

@Controller
public class SimpleController {

  private final SimpleViewComponent simpleViewComponent;

  public TestController(SimpleViewComponent simpleViewComponent) {
    this.simpleViewComponent = simpleViewComponent;
  }

  @GetMapping("/")
  ViewContext simple() {
    return simpleViewComponent.render();
  }
}

Perfect fit for HATEOAS

Spring ViewComponent is a perfect fit for building hypermedia-driven web applications.

When the user interacts with the application the state of the application on the server changes.
We now need to send HTML back to swap it into the DOM to reflect the changes in the UI.

With server-side rendered ViewComponents we can call the render method of a ViewComponent again and swap out that component.

Example Application

To explain the benefits I will show you a simple user management application, where we can edit and create users.

If you want to build along, a more detailed guide can be found in my workshop:
Building server-side web applications with htmx

You can play around with the application at htmx.tschuehly.de. Open the DevTools and look at what requests are happening when you interact with the application!

When we want to create/edit a user a modal pops up. The modal is closed when we save the user.

A new table row is automatically appended to the top of the table when we save a new user. When we edit and save an existing user the table row is updated.

This is where Spring ViewComponent comes in. Each part of the UI is a ViewComponent.

We have a UserTableComponent, a UserRowComponent, an EditUserFormComponent and a CreateUserFormComponent.

When we click on the Create new User button htmx will create an HTTP GET request to the /create-user/modal endpoint.

<!-- UserTableComponent.jte -->
<button hx-get="${GET_CREATE_USER_MODAL}" 
        hx-target="#${MODAL_CONTAINER_ID}">
  Create new User
</button>

This will return the HTML of the CreateUserFormComponent that will be rendered in the element with the id: MODAL_CONTAINER_ID

// UserController.java
public static final String GET_CREATE_USER_MODAL = "/create-user/modal";
@GetMapping(GET_CREATE_USER_MODAL)
public ViewContext getCreateUserModal() {
  return createUserComponent.render();
}

When we click on Save User an HTTP POST request is created to the /create-user endpoint.

// UserController.java
public static final String POST_CREATE_USER = "/create-user";
@PostMapping(POST_CREATE_USER)
public ViewContext createUser(String username, String password) {
  EasyUser user = userService.createUser(username, password);
  return userRowComponent.renderNewRow(user);
}

This will first create a new user. Then it will call the UserRowComponent.renderUserRow with the updated user.

// UserRowComponent.java
public ViewContext renderNewRow(EasyUser user) {
  HtmxUtil.retargetId(UserTableComponent.USER_TABLE_BODY_ID);
  HtmxUtil.reswap(HxSwapType.AFTER_BEGIN);
  HtmxUtil.trigger(UserManagementComponent.CLOSE_MODAL_EVENT);
  return new UserRowContext(user);
}

Normally with htmx you define the target, swap and trigger behaviour with hx-attributes. I prefer defining them with HX- reponse headers in the component method. This decouples the source template from the target component.

Here we tell htmx to target the UserTableComponent body, insert the response before the first child and then trigger the CLOSE_MODAL_EVENT

<!-- UserRowComponent.jte -->
!{var uuid = userRowContext.easyUser().uuid;} 
<tr id="${UserRowContext.htmlUserId(uuid)}">
    <td>
        ${uuid.toString()}
    </td>
    <td>
        ${userRowContext.easyUser().username}
    </td>
    <td>
        ${userRowContext.easyUser().password}
    </td>
    <td>
        <button hx-get="${URI(UserController.GET_EDIT_USER_MODAL,uuid)}"
                hx-target="#${MODAL_CONTAINER_ID}">
            <img src="/edit.svg">
        </button>
    </td>
</tr>

The UserRowComponent.jte has an edit button that calls the GET_EDIT_USER_MODAL endpoint with the uuid of the user as parameter.

After editing a user we need to swap the row of the user we just changed. We can create a rerender method and call it from the corresponding endpoint.

// UserRowComponent.java
public ViewContext rerender(EasyUser easyUser) {
  String target = HtmxUtil.target(UserRowContext.htmlUserId(easyUser.uuid)); 
  HtmxUtil.retarget(target); 
  HtmxUtil.reswap(HxSwapType.OUTER_HTML);
  HtmxUtil.trigger(UserManagementComponent.CLOSE_MODAL_EVENT);
  return new UserRowContext(easyUser); 
}

Advanced Patterns

With Spring ViewComponent we can leverage Dependency Injection to compose the UI while adhering to the open–closed principle.

Another interesting topic is declarative UI with the Strategy Pattern. I have an example repository here: github.com/tschuehly/svc-ui

Lastly we can create higher level abstractions on top of the simple concept of swapping Elements in the DOM that are specific to our domain and use cases.

I will create more blog posts in the future showing the patterns we use at alanda.io to create an enterprise application with Spring ViewComponent and htmx.

If you want to learn more about HTMX + Spring Boot check out my series Web development without the JavaScript headache with Spring + HTMX.

My side business PhotoQuest is also built with HTMX + JTE

plugins {
    id("java-test-fixtures")
}

This will allow you to create a new source set in src/testFixtures where you can define the test code you want to share with other modules.

In Gradle you can use these textFixtures easily with:

testImplementation(testFixtures("de.tschuehly:spring-view-component-core:0.7.3-SNAPSHOT"))

If you want to use these Gradle test fixtures in a maven project you need to add the dependency with the test-fixtures classifier:

<dependency>
  <groupId>de.tschuehly</groupId>
  <artifactId>spring-view-component-core</artifactId>
  <version>${view.component.version}</version>
  <classifier>test-fixtures</classifier>
</dependency>

If you want to learn more about HTMX + Spring Boot check out my series Web development without the JavaScript headache with Spring + HTMX.

My side business PhotoQuest is also built with HTMX + JTE

Probably everyone has experienced that JavaScript headache when it behaves like a well-tested modern language:

htmx to the rescue

htmx enables us to create interactive web applications with server-side rendered templates without JavaScript.
It enables interactivity by swapping parts of the DOM when new information is requested from the server.

We leverage the REST constraint "Hypermedia as the Engine of Application State".

With HATEOAS we don't send JSON to the Browser and render the page on the client.
Instead, the Server provides the presentation of information (HTML) and the application control information embedded within (htmx attributes).

This decouples the client and server at the network level.
It enables the server to evolve independently from the client, as the server provides the data and how to interact with the server based on that data.

Spring UserManagement Application

We have a table of users and we want to be able to edit users only with the power of HATEOAS and htmx.

We are using JTE as the server-side template language. CSS is omitted for the sake of readability.

Display a List of Users

We add an easyUserList attribute to our MVC model.
(I explain the MVC pattern here Spring MVC explained: Spring I/O 2023.)
We also define a constant for the UserTable ID and an ID for a modal container.

// UserController.java
@Controller
public class UserController {
  public static final String MODAL_CONTAINER_ID = "modalContainer";
  public static final String USER_TABLE_BODY_ID = "userTableBody";
  @Autowired
  private final UserService userService;

  @GetMapping("/")
  public String userManagement(Model model) {
    model.addAttribute("easyUserList", userService.findAll());
    return "UserManagement";
  }
}

We add this easyUserList as a parameter to the template.
In the table body, we loop over the easyUserList and call the userRow JTE template.

<!-- UserManagement.jte -->
@import static de.tschuehly.easy.spring.auth.controller.UserController.*
@param List<EasyUser> easyUserList
<table>
    <!-- thead omitted -->
    <tbody id="${USER_TABLE_BODY_ID}">
    @for(var user: easyUserList)
        @template.userRow(easyUser = user)
    @endfor
    </tbody>
</table>
<div id="${MODAL_CONTAINER_ID}"></div>

Display one User as Table Row

The UserRow template defines an EasyUser parameter and a local variable with the exclamation mark JTE expression: !{var name = value} .

<!-- UserRow.jte -->
@import de.tschuehly.easy.spring.auth.domain.EasyUser
@import static de.tschuehly.easy.spring.auth.controller.UserController.*
@param EasyUser easyUser
!{var uuid = easyUser.uuid.toString();}
<tr id="user-${uuid}">
    <td>
        ${uuid}
    </td>
    <td>
        ${easyUser.username}
    </td>
    <td>
        ${easyUser.password}
    </td>
    <td>
        <button hx-get="${URI(EDIT_USER_MODAL,uuid)}"
                hx-target="#${MODAL_CONTAINER_ID}">
            <img src="/edit.svg">
        </button>
    </td>
</tr>

As you can see we are using static constants heavily, to make it easy to understand what controller mappings htmx sends requests to.

hx-get="${URI(EDIT_USER_MODAL,uuid)} creates an HTTP get request to /user/edit/{uuid} when the button element is clicked. The uuid variable is interpolated with a static URI method we will define next.

hx-target="#${MODAL_CONTAINER_ID}" tells HTMX to swap the response body with the element that has the id value "modalContainer".

If we now go to the localhost:8080 we can see the table rendered:

Edit User attributes

// UserController.java
@Controller
public class UserController {
  @Autowired
  private final UserService userService;

  public static final String MODAL_CONTAINER_ID = "modalContainer";
  public static final String EDIT_USER_MODAL = "/user/edit/{uuid}";

  public record UserForm(String uuid, String username, String password) {}

  @GetMapping(EDIT_USER_MODAL)
  public String editUserModal(Model model, @PathVariable UUID uuid) {
    var user = userService.findById(uuid);
    model.addAttribute("userForm", new UserForm(
        user.uuid.toString(), user.username, user.password
    ));
    return "EditUserForm";
  }

  public static String URI(String uriTemplate, Object... variables) {
    return new UriTemplate(uriTemplate)
        .expand(variables).toString();
  }

}

The EDIT_USER_MODAL endpoint adds a UserForm record to the model with the values retrieved from the UserService.

The EditUserForm.jte template displays a form with an hx-post attribute to "/create-user" that we reference by the static constant "CREATE_USER".

<!-- EditUserForm.jte -->
@import static de.tschuehly.easy.spring.auth.controller.UserController.SAVE_USER
@param de.tschuehly.easy.spring.auth.controller.UserController.UserForm userForm
<form>
    <label>
        UUID
        <input type="text" readonly name="uuid" value="${userForm.uuid()}">
    </label>
    <label>
        Username
        <input type="text" name="username" value="${userForm.username()}">
    </label>
    <label>
        Password
        <input type="text" name="password" value="${userForm.password()}">
    </label>
    <button type="submit" hx-post="${SAVE_USER}">
        Save User
    </button>
</form>

When clicking on the edit button the EditUserForm is rendered in the modalContainer.

Save changed User attributes

In the controller method, we save the user and add the saved user to the model.

We add HX-Retarget = #user-${user.uuid}to target the table row <tr> element that contains the user we just edited.
With HX-Reswap = outerHTML we tell htmx to swap the whole table row.

@Controller
public class UserController {
  public static final String SAVE_USER = "/save-user";
  public static final String CLOSE_MODAL_EVENT = "close-modal";

  @PostMapping(SAVE_USER)
  public String saveUser(UUID uuid, String username, String password, Model model,
      HttpServletResponse response) {
    EasyUser user = userService.saveUser(
        uuid,
        username,
        password
    );
    model.addAttribute("easyUser", user);
    response.addHeader("HX-Retarget", "#user-" + user.uuid);
    response.addHeader("HX-Reswap", "outerHTML");
    response.addHeader("HX-Trigger", CLOSE_MODAL_EVENT);
    return "UserRow";
  }
}

With HX-Trigger = close-modal we tell htmx to trigger a JavaScript event close-modal in the browser when the HTTP response is received.

We add an hx-on: attribute to clear the innerHTML of the modalContainer to remove the HTML from the DOM when the event is triggered.

<div id="${MODAL_CONTAINER_ID}" 
     hx-on:$unsafe{CLOSE_MODAL_EVENT}="this.innerHTML = null">
</div>

If we click the Save User button and go to Chrome DevTools we can see HATEOAS in action.
The new application state after saving the user is transferred via HTML to the browser.

We have created a fully interactive web application without leaving our lovely JVM!

You can find the source code of this tutorial at github.com/tschuehly/easy-spring-auth.
If you have questions ping me on twitter.com/tschuehly.

If you want to learn more about server-side rendering with Spring Boot you can find more information here: github.com/tschuehly/fullstack-with-spring

If you want to learn more about HTMX + Spring Boot check out my series Web development without the JavaScript headache with Spring + HTMX.

My side business PhotoQuest is also built with HTMX + JTE

But creating a web frontend without leaving your favourite Java Framework is easy!

We go to everyone's 2nd favorite place online: start.spring.io and create a new project.
We will not choose a template language as you can sadly not find the best template language there!

Instead, we go to jte.gg and add the latest spring-boot-starter as a dependency to our project.

implementation("gg.jte:jte-spring-boot-starter-3:3.1.9")
implementation("gg.jte:jte:3.1.9")

We start with a WebController and define our Data model.
We have a Link record which has a displayValue and a hrefValue field.
We also have a SpringResources record which has a topics HashMap field.

@Controller
public class WebController {
  public record Link(String displayValue, String hrefValue) {}

  public record SpringResources(HashMap<String, List<Link>> topics) {}
}

Then we create a JTE template in a new file located in src/main/jte/spring.jte
As JTE is compiled to Java we start by importing the SpringResources record.
JTE expects a parameter of type SpringResources in the model

@import com.bootiful.frontend.web.WebController.SpringResources
@param SpringResources springResources

We use the @for syntax to loop through the hashMap entrySet and show a heading for each key.

@import com.bootiful.frontend.web.WebController.SpringResources
@param SpringResources springResources

@for(var resource: springResources.topics().entrySet())
    <h2>
        ${resource.getKey()}
    </h2>
@endfor

Then we create an <ul> tag for each topic. Then for each link object in the list, we create a <li> tag and a <a> tag with the href set to the hrefValue, and render the displayValue inside the tag.

@import com.bootiful.frontend.web.WebController.SpringResources
@param SpringResources springResources

@for(var resource: springResources.topics().entrySet())
    <h2>
        ${resource.getKey()}
    </h2>
    <ul>
        @for(var link: resource.getValue())
            <li>
                <a href="${link.hrefValue()}">${link.displayValue()}</a>
            </li>
        @endfor
    </ul>
@endfor

Now we add a Controller Endpoint where we add a new SpringResource object to the Model as springResources attribute.
Then we return a spring string which is a reference to the spring.jte template.

@Controller
public class WebController {
  ...
  @GetMapping("/")
  public String index(Model model) {
    model.addAttribute("springResources", new SpringResources(new HashMap<>(
        Map.of("Spring",List.of(
            new Link("Spring","https://spring.io"),
            new Link("Spring Academy","https://spring.academy")
        ))
    )));
    return "spring";
  }
}

If we now navigate to http://localhost:8080/ you can see that our template is rendered correctly:

You can find the source code for this tutorial here: github.com/tschuehly/bootiful-frontend

If you want to learn more about HTMX + Spring Boot check out my series Web development without the JavaScript headache with Spring + HTMX.

My side business PhotoQuest is also built with HTMX + JTE

In my htmx project, I wanted to use a hosted authentication provider. I did not want to deal with user credentials myself.

I researched the market and found Supabase which had an interesting offering for free!

• 50.000 monthly active users

• Hosted Postgres server with 500 MB storage

This was definitely sufficient for my side projects!

However the Supabase Authentication was built on GoTrue and was not ready to be integrated into my Spring Boot application.

That is why I decided to create the htmx-supabase-spring-boot-starter!

Key features:

• Supabase Authentication integration

• Spring Security configuration with application.yaml/properties

• Role-Based Access Control

• Basic Authentication

Integrating htmx-supabase-spring-boot-starter

The setup is straightforward ->

Add the Dependency

implementation("de.tschuehly:htmx-supabase-spring-boot-starter:0.3.0")

Configure your application.yaml:

supabase:
  projectId: yourProjectId
  anonKey: ${SUPABASE_ANON_KEY}
  databasePassword: ${SUPABASE_DATABASE_PW}
  jwtSecret: ${SUPABASE_JWT_SECRET}
  successfulLoginRedirectPage: "/account"
  passwordRecoveryPage: /updatePassword
  unauthenticatedPage: /unauthenticated
  unauthorizedPage: /unauthorizedPage
  sslOnly: false

Add the necessary public paths:

supabase:
  public:
    get:
      - "/unauthenticated"
      - "/unauthorized"
      - "/api/user/logout"
    post:
      - "/api/user/signup"
      - "/api/user/sendEmailOtp"
      - "/api/user/login"
      - "/api/user/jwt"
      - "/api/user/sendPasswordResetEmail"

Add the javascript snippets that authorize a user after login:

<script>
    if (window.location.hash.startsWith("#access_token")) {
        htmx.ajax('POST', '/api/user/jwt', {target: '#body', swap: 'outerHTML'})
            .then(window.location.hash = "")
    }
</script>

Now add a signup form:

<form>
    <label>Email:
        <input type="text" name="email"/>
    </label>
    <label>Password:
        <input type="password" name="password"/>
    </label>
    <button hx-post="/api/user/signup">Submit</button>
</form>

And a login form:

<form>
    <label>Email:
        <input type="text" name="email"/>
    </label>
    <label>Password:
        <input type="password" name="password"/>
    </label>
    <button hx-post="/api/user/login">Submit</button>
</form>

That's it! You now have a secured Spring Boot + htmx application, where a user can register and then log in.

If you want to dive deeper into the configuration, you can check out the README in the GitHub repo:

github.com/tschuehly/htmx-supabase-spring-boot-starter

If you want to learn more about HTMX + Spring Boot check out my series Web development without the JavaScript headache with Spring + HTMX.

My side business PhotoQuest is also built with HTMX + JTE

You can grab the release from Maven Central by following the instructions at: https://github.com/tschuehly/spring-view-component#installation

The two biggest changes to this release are the annotation processor for processing ViewComponents at build time and an improved way to create a ViewContext.

Annotation Processor

Previously the templates were processed at request time by parsing them with jsoup and then transforming the view:action attributes after rendering the templates was finished.

This was complicated as we needed to deal with HTML parsing and figuring out what ViewComponent the view:action attribute was in and severely impacted performance, as this was done on each request and not just once.

Now a Java annotation processor will process the templates at build time to translate the view:action attributes to hx- attributes.

But hot reloading the templates also still works as I integrated a Spring Devtools FileSystem Watcher to parse the templates at development time.

Creating a ViewContext

Previously we created a ViewContext by calling the ViewContext constructor and passing ViewProperties.

This will now be replaced by creating a dedicated record that needs to implement the ViewContext interface. This will enable type checking of templates in the future.

This simplifies the @param annotation inside JTE templates and the @thymesVar comment inside Thymeleaf templates immensely!

If you have any questions just open an issue in the GitHub Repository!

If you want to learn more about HTMX + Spring Boot check out my series Web development without the JavaScript headache with Spring + HTMX.

My side business PhotoQuest is also built with HTMX + JTE

What is Microstream?

MicroStream is a Java native persistence layer that can store a Java Object Graph in a binary storage format, persisting it across application restarts.

With MicroStream your data lives in your RAM giving you blazingly fast access times.

Why do we want MicroStream

I wanted to try out using MicroStream after using JPA for most of my developer career as I was looking to simplify my data storage, after hearing about it at JCON 2023.

I'm very interested in making my application as simple as possible to ease development and get to production faster.

They market MicroStream heavily for microservices, but I think the best use case is a fat modulith running on a VPS at Hetzner or similiar.

You can get a 32 Core,64 Thread dedicated Server with 1TB of RAM for 530€ a month at Hetzner, or a 128 Core, 256 Thread dedicated Server with 2TB of RAM for 2400€ a month at hostcircle.nl. Tell me the workload that doesn't fit on that machine.

Migrating to JPA

MicroStream has support for Spring Boot. As we want to store a Java Object Graph we need to define a Root Node for the Graph.

We can do that with the @Storage annotation:

@Storage
class Root {
    @Autowired
    @Transient
    private lateinit var storageManager: StorageManager
    //...
}

We autowire the StorageManager that is responsible for interacting with MicroStream.

We want to have a primary key for every Object in the DataStore to emulate the Database behavior we are used to.

Instead of a Database Table PERSON we create a mutableMap with a Long Key and a Person Value.

We also create an AtomicLong as an Index and create a function that increases the index and stores it.

@Storage
class Root {
    //...
    val personMap = mutableMapOf<Long, Person>()

    private val index: AtomicLong = AtomicLong(0)

    fun newIndex(): Long {
        val newIndex = index.incrementAndGet()
        storageManager.store(index)
        return newIndex
    }
}

We create a generic store function to store our map in our Root Object

class Root{
    //...
    fun <T> store(map: MutableMap<Long, T>) {
        storageManager.store(map)
    }
}

To emulate the CrudRepository we know from JPA, I created a generic CrudRepository which we can implement in our Domain Repositories. It expects a TypeArgument which implements the Entity interface which has an id parameter.

It exposes methods like getAll, getByIdOrNull, save, and saveAll.

open class CrudRepository<T : Entity>(
    open val root: Root,
    private val mutableMap: MutableMap<Long, T>,
) {
    private val lock: ReentrantReadWriteLock = ReentrantReadWriteLock()
    fun getAll(): List<T> {
        return readAction {
            mutableMap.values.toList()
        }
    }

    fun getByIdOrNull(id: Long): T? {
        return readAction{
            mutableMap[id]
        }
    }

    fun save(obj: T): T {
        return writeAction{
            (obj.id ?: root.newIndex()).let { id ->
                obj.id = id
                mutableMap[id] = obj
                store()
            }
            obj
        }

    }

    fun saveAll(objList: List<T>): List<T> {
        return writeAction{
            val objMap = objList.map { obj ->
                (obj.id ?: root.newIndex()).let { id ->
                    obj.id = id
                    return@map Pair(id,obj)
                }
            }.toMap()
            mutableMap.putAll(objMap)
            store()
            objMap.values.toList()
        }
    }
    private fun store(){
        root.store(mutableMap)
    }

    open fun <T> readAction(supplier: Supplier<T>): T {
        lock.readLock().lock()
        return try {
            supplier.get()
        } finally {
            lock.readLock().unlock()
        }
    }

    open fun <T> writeAction(supplier: Supplier<T>): T {
        lock.writeLock().lock()
        return try {
            supplier.get()
        } finally {
            lock.writeLock().unlock()
        }
    }
}

We can now implement a JPA style PersonRepository extending our CrudRepository.

In this example we create a findByName function that filters through all map values by name.

@Repository
class PersonRepository(
    override val root: Root
) : CrudRepository<Person>(root, root.personMap){
    fun findByName(name: String): List<Person> {
        return readAction {
            root.personMap.values.filter {
                it.name == name
            }
        }
    }
}

Example

You can find the example in the GitHub Repository

If you want to learn more about HTMX + Spring Boot check out my series Web development without the JavaScript headache with Spring + HTMX.

My side business PhotoQuest is also built with HTMX + JTE

To fix this we need to configure your Spring App and Prometheus with Basic Authentication and configure Prometheus to access the Actuator Endpoints.

To set up your Prometheus + Grafana Setup you can follow the excellent guide on Refactor First: Monitoring Spring Boot Application with Prometheus and Grafana by Amrut Prabhu

Custom SecurityConfig

After you got everything working without Authentication you need to configure your SecurityConfiguration like this:

@Configuration
@EnableWebSecurity
class SecurityConfig{
    val logger: Logger = LoggerFactory.getLogger(SupabaseSecurityConfig::class.java)

    @Bean
    fun filterChain(
        http: HttpSecurity,
        authManager: AuthenticationManager
    ): SecurityFilterChain {
        http.invoke {
            authorizeHttpRequests {
                authorize(EndpointRequest.toAnyEndpoint(), hasRole("ACTUATOR"))
                authorize(anyRequest, authenticated)
            }
            authenticationManager = authManager
            httpBasic {}
        }
        return http.build()
    }

    @Bean
    fun authManager(
        http: HttpSecurity
    ): AuthenticationManager {
        val authenticationManagerBuilder = http.getSharedObject(
            AuthenticationManagerBuilder::class.java
        )
        authenticationManagerBuilder.inMemoryAuthentication()
            .withUser("prometheus")
            .password("{bcrypt}\$2a\$\$LVUNCy8Lht68w7KA0nobWuwyzbW8AdF3bRC25glv7M12ACAZ4PT8u")
            .roles("ACTUATOR")
        return authenticationManagerBuilder.build()
    }

}

Using a custom authenticationManager gives us the ability to add other AuthenticationProviders using:

authenticationManagerBuilder.authenticationProvider(customAuthenticationProvider)

Supabase Security Spring Boot Starter

If you are using the Supabase Security Spring Boot Starter it is even easier!

supabase:
  basicAuth:
    enabled: true
    username: prometheus
    password: "{bcrypt}$2a$10$AqgP120RLJ48mvTv.diNHeVlQA/WdsrgEr0aLe5P1ffYPy1FQAecy"
    roles:
      - "ACTUATOR"
  roles:
    admin:
      get:
        - "/actuator/**"

You can encrypt the password using the Spring Boot CLI

Prometheus

Then you can configure your prometheus.yaml with the basic auth credentials:

scrape_configs:
- job_name: 'Spring Boot Application input'
  metrics_path: '/actuator/prometheus'
  scrape_interval: 2s
  static_configs:
    - targets: ['localhost:8080']
      labels:
      application: 'My Spring Boot Application'
      basic_auth:
      username: "prometheus"
      password: "plain-text-password"

If you want to learn more about HTMX + Spring Boot check out my series Web development without the JavaScript headache with Spring + HTMX.

My side business PhotoQuest is also built with HTMX + JTE