j-sui

Server-rendered UI for Java: keep rendering, actions, and state on the server, then patch the browser with lightweight HTTP/WebSocket responses.

Status: experimental. APIs may change.

For full framework documentation, see documentation.md.

Why j-sui

• Keep UI logic in Java instead of splitting behavior across backend + SPA.
• Render plain HTML strings with utility classes and small built-in client helpers.
• Patch only changed parts of the page (inline, outline, append, prepend, none).
• Use WebSocket patches for live updates, with HTTP action fallback.
• Avoid frontend build pipelines for server-driven apps.

Requirements

• Java 21+
• Maven 3.9+

Quick Start

Run the showcase app:

mvn compile
mvn exec:java
# open http://localhost:1422

Run tests:

mvn test

Minimal Example

import jsui.App;
import jsui.Server;
import jsui.ui;

public final class Hello {
    public static void main(String[] args) throws Exception {
        App app = new App("en");

        app.Page("/", ctx -> {
            ui.Target target = ui.Target();

            String body = ui.div("p-6 space-y-4").render(
                    ui.div("text-xl font-semibold").render("Hello from j-sui"),
                    ui.div("text-gray-700", target.id()).render("Click the button"),
                    ui.Button()
                            .Color(ui.Blue)
                            .Click(ctx.Call(c -> ui.div("text-gray-700", target.id()).render("Updated")).Replace(target.id()))
                            .Render("Update"));

            return app.HTML("Hello", "bg-gray-100 min-h-screen", body);
        });

        Server.builder(app).httpPort(1422).start();
    }
}

Core APIs

• App: route/page registration, document shell, static assets, session wiring.
• Context: action handlers, form binding (ctx.Body(model)), response patching/scheduling.
• ui: HTML/form builders, target helpers, style constants, theme switcher.
• Server: Java SE HTTP/WebSocket runtime for requests and patch delivery.
• Data: reusable collate/table utilities with filtering, sorting, pagination, and export.

Interaction Model

• ctx.Call(handler) creates event handlers for clicks and custom actions.
• ctx.Submit(handler) wires form submission handlers.
• Use target actions to control swap behavior (Replace, Render, Append, Prepend).
• Push updates later with ctx.Patch(...), ctx.Defer(...), ctx.Repeat(...), ctx.Delay(...).

Assets and Theming

• Tailwind is injected via @tailwindcss/browser CDN in App by default.
• ui.ThemeSwitcher("") enables light/dark/system switching.
• Serve static files from classpath:

app.AssetsFromClasspath("/assets", "public/assets", 86400);
app.FaviconFromClasspath("/assets", "public/favicon.ico", 86400);

Project Layout

• Core framework: src/main/java/jsui
• Showcase app entry: src/main/java/jsui/examples/Main.java
• Example pages: src/main/java/jsui/examples/pages
• Tests: src/test/java

Build and Packaging

mvn clean compile
mvn package
mvn clean native:compile

After native build:

./target/j-sui

License

MIT - see LICENSE.