Kilua Web Framework

Kilua supports true SSR by allowing the same application code to run in both the browser and a Node.js environment. This is achieved by using a compatible router class.

Key SSR Features:

• State Serialization: Application state is serialized from the server to the client.
• CSS Extraction: CSS styles are automatically extracted from the JS bundle and injected into the HTML.
• Fullstack Integration: Supports external API calls and Kilua RPC services.
• Server Modules: Ready-to-use modules are available for Ktor, Spring Boot, Micronaut, Javalin, Jooby, and Vert.x.

SSR Limitations:

• State Source: The URL address and browser preferred locale should be the only sources of application state.
• Browser APIs: Direct use of browser APIs is not recommended during SSR.
• Advanced Components: Complex JS components (e.g., RichText, Tabulator) render as simple HTML placeholders on the server.
• Authentication: Rendering authenticated content is currently not supported.
• Hydration: Implemented via a simple replacement of rendered content.

To build and run Kilua examples, you must have JDK 21 or later installed. Use ./gradlew on Unix-like systems or gradlew.bat on Windows.

Frontend Development (JS/Wasm)

Use the -t flag for continuous build mode (webpack dev server) on http://localhost:3000.

Fullstack and SSR

For fullstack or SSR applications, additional tasks are available for running backend servers and exporting static sites.

# Run JS target in continuous build mode
./gradlew -t :examples:[exampleName]:jsBrowserDevelopmentRun

# Run Wasm target in continuous build mode
./gradlew -t :examples:[exampleName]:wasmJsBrowserDevelopmentRun

# Build production JS application
./gradlew :examples:[exampleName]:jsBrowserDistribution

# Build production Wasm application
./gradlew :examples:[exampleName]:wasmJsBrowserDistribution

# Run backend for fullstack/SSR development
./gradlew :examples:[exampleName]:jvmRun

# Export static site with JS frontend
./gradlew :examples:[exampleName]:exportWithJs

A basic Kilua application extends the Application class and overrides the start() method. Inside start(), you use the root(id) function to define the application entry point in the DOM. State management is handled using Compose primitives like remember and mutableStateOf.

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import dev.kilua.Application
import dev.kilua.CoreModule
import dev.kilua.compose.root
import dev.kilua.html.button
import dev.kilua.html.div
import dev.kilua.html.unaryPlus
import dev.kilua.startApplication

class App : Application() {

    override fun start() {
        root("root") {
            var state by remember { mutableStateOf("Hello, world!") }

            div {
                +state
            }
            button("Add an exclamation mark") {
                onClick {
                    state += "!"
                }
            }
        }
    }
}

fun main() {
    startApplication(::App, CoreModule)
}

Kilua uses Gradle tasks to manage development servers and production builds for both JavaScript (JS) and WebAssembly (Wasm) targets. Tasks are categorized by the build tool used (Vite vs. Webpack/Browser Distribution).

### Vite Tasks
# JS Target
./gradlew jsViteRun                # Run Vite dev server on http://localhost:3000
./gradlew -t jsViteCompileDev      # Continuous development compilation
./gradlew jsViteBuild             # Build production to build/vite/js/dist

# Wasm Target
./gradlew wasmJsViteRun            # Run Vite dev server on http://localhost:3000
./gradlew -t wasmJsViteCompileDev  # Continuous development compilation
./gradlew wasmJsViteBuild         # Build production to build/vite/wasmJs/dist

### Webpack / Browser Distribution Tasks
# JS Target
./gradlew -t jsBrowserDevelopmentRun      # Continuous build mode on http://localhost:3000
./gradlew jsBrowserDistribution            # Build production to build/dist/js/productionExecutable

# Wasm Target
./gradlew -t wasmJsBrowserDevelopmentRun  # Continuous build mode on http://localhost:3000
./gradlew wasmJsBrowserDistribution       # Build production to build/dist/wasmJs/productionExecutable

To create a Kilua application, extend the Application class and implement the start and dispose methods:

• start(state: String?): The entry point for your UI logic. It receives an optional state string, which can be used to restore application state (e.g., from SSR or a previous session). Inside start, use root("id") to attach your component tree to a specific HTML element.
• dispose(): String: Called when the application is being shut down. You should return a string representation of the current application state so it can be passed back into start during the next initialization.

class App : Application() {
    var counter by mutableStateOf(0)

    override fun start(state: String?) {
        if (state != null) {
            counter = state.toInt()
        }
        root("root") {
            // UI components go here
        }
    }

    override fun dispose(): String {
        return counter.toString()
    }
}