Void

A minimal Kotlin web framework for building HTML pages and APIs with a tiny HTTP/HTTPS server.

Void is a small, unopinionated framework you can embed into your app. It provides:

• Simple router with static and dynamic routes
• Middleware (before/after) with priorities
• First-class API endpoints returning ResponseDTO
• Minimal HTTP/HTTPS server (no servlet container)
• Bootstrapper for external modules (page decorators, special routes, error handlers)

Quick links

• Security policy: SECURITY.md
• Roadmap/TODO: TODO.md
• Contributing guide: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Support: SUPPORT.md
• License: MIT (LICENSE)
• Wiki: DeepWiki

• Language: Kotlin 2.2.21
• Build System: Gradle 8.x+ (Kotlin DSL)
• Minimum Java: 8 (for library consumers), 21 (for building the project)
• Frameworks: kotlinx-serialization (JSON, CBOR, Protobuf), SLF4J
• Distribution: JitPack

• void-base/: The core framework library.
  • src/main/kotlin/io/voidx/: Core server, router, and DTO logic.
  • src/main/kotlin/io/voidx/bootstrap/: Module bootstrapping system.
• gradle/: Gradle wrapper and version catalogs.

• JDK 21+ (to build)
• JDK 8+ (to run)

Add the repository and dependency:

repositories {
    mavenCentral()
    maven(url = "https://jitpack.io")
}

dependencies {
    implementation("com.github.Jadiefication:Void:VERSION")
}

Create a minimal server with one text route and one JSON route:

fun main() {
    val server = io.voidx.simpleServer {
      io.voidx.page.route("/") {
        GET {
          io.voidx.dto.ok("Hello, Void!", mutableMapOf("Content-Type" to "text/plain"))
        }
      }

      // JSON route
      io.voidx.page.route("/api/health") {
        GET {
          io.voidx.dto.buildResponse<String> {
            status = 200
            statusText = "OK"
            headers["Content-Type"] = "application/json"
            body = "{\"status\":\"ok\"}"
          }
        }
      }
    }
}

Then open http://localhost:8080

The project uses Gradle for all common tasks:

• ./gradlew build: Build all modules.
• ./gradlew test: Run all tests.
• ./gradlew jacocoRootReport: Generate an aggregate test coverage report (found in build/reports/jacoco/jacocoRootReport/html/index.html).
• ./gradlew ktlintCheck: Run linting checks.

Void is designed to be unopinionated and doesn't rely on specific environment variables by default.

Void doesn’t force a particular logging, DI, templating, or persistence stack. Compose apps using functions and small DSLs. Middleware integrates via a simple interception mechanism.

Request handling uses Kotlin coroutines under the hood to keep I/O non-blocking with a straightforward API.

Pages and routers can be constructed and invoked in tests without spinning up external containers. You can exercise handlers directly or run the tiny server in integration tests.

Core entry points:

• io.voidx.router.router { } — Create and configure a router.
• io.voidx.page.route("/path") { GET { ... } } — Define a page/route.
• io.voidx.Server — Start HTTP/HTTPS servers.
• io.voidx.middleware.Relay — Middleware base for relayBefore / relayAfter.
• io.voidx.bootstrap.Bootstrap — Module bootstrapper and DX helpers.

Void exposes a lightweight bootstrapper so external modules can hook into internals:

• Page decorators: Run once when a page is added.
• Special routes: Prioritized pre-dispatch handlers.
• Error handlers: Observe/handle errors produced by the router.

Example module:

class MyModule : io.voidx.bootstrap.Bootstrap.Module {
    override fun onRouterCreated(ctx: io.voidx.bootstrap.Bootstrap.Context) {
        ctx.addRoute(
            io.voidx.page.route("/hello") { GET { io.voidx.dto.ok("hi", mutableMapOf("Content-Type" to "text/plain")) } }
        )
    }
}

Register modules via META-INF/services/io.voidx.bootstrap.Bootstrap$Module.

The test suite is authoritative and aims for high coverage.

• Run tests: ./gradlew test
• Coverage: ./gradlew jacocoRootReport

We welcome contributions! Please see CONTRIBUTING.md and CODE_OF_CONDUCT.md.

MIT — © 2025 Jadiefication