Drastically speeds server development with high-level abstractions for databases, cache, email, SMS, and file storage; typed HTTP/WebSocket endpoints, auth flows, auto-generated docs and SDKs, Terraform output.
Lightning Server is a Kotlin server framework for building production backends faster. You define typed endpoints, service settings, and authentication rules in plain Kotlin; the framework handles HTTP routing, SDK generation, unit testing (no running server required), and — the standout feature — derives your complete AWS Terraform infrastructure from the same server definition. Add a service setting; get the matching cloud resource automatically.
Status: pre-release (version 5). The API is settling and breaking changes are still possible. The nightly badge above tracks the latest published build.
Add these imports at the top of your file:
import com.lightningkite.lightningserver.*
import com.lightningkite.lightningserver.auth.*
import com.lightningkite.lightningserver.definition.builder.*
import com.lightningkite.lightningserver.http.*
import com.lightningkite.lightningserver.pathing.*
import com.lightningkite.lightningserver.runtime.test.*
import com.lightningkite.lightningserver.typed.*
import kotlinx.coroutines.*
import kotlinx.serialization.*
The minimal server is a ServerBuilder object:
object HelloServer : ServerBuilder() {
// GET / — responds with a plain-text greeting
val root = path.get bind HttpHandler {
HttpResponse.plainText("Hello, Lightning Server!")
}
}
Test it without starting a server:
fun helloServerTest() = runBlocking {
HelloServer.test(settings = {}) {
val response = HelloServer.root.test()
check(response.body?.text() == "Hello, Lightning Server!")
}
}
For the full walkthrough — imports, typed endpoints, auth, database, testing, and AWS deployment — start with the guide: Your First Endpoint
The docs-guide/ module contains compiled-sample chapters: every code block is
drift-checked against the compiled source on every CI run.
The older
docs/directory contains reference documentation for the previous API surface. It is retained for background but may not match the current version-5 API.
# Build all modules
./gradlew build
# Run checks (tests + linting)
./gradlew check
# Assemble without running tests
./gradlew assemble
# Run just the docs-guide tests (verifies all guide code blocks)
./gradlew :docs-guide:test
# Run tests for a specific module
./gradlew :core:test
# Run the demo server (Ktor — recommended for development)
./gradlew :demo:run --args=
./gradlew :demo:run --args=
./gradlew :demo:run --args=
./gradlew :demo:run --args=
./gradlew publishToMavenLocal
The project follows a paired pattern: most features have a *-shared
multiplatform module (KMP; used by client SDKs) and a JVM module.
Service implementations (MongoDB, Redis, S3, SES, etc.) live in the separate service-abstractions repository and are brought in as dependencies.
Artifacts are published to the Lightning Kite Maven repository. Add the
repository and dependency to your build.gradle.kts:
repositories {
maven("https://lightningkite-maven.s3.us-west-2.amazonaws.com")
mavenCentral()
}
dependencies {
// Core + typed endpoints
implementation("com.lightningkite.lightningserver:core:<version>")
implementation("com.lightningkite.lightningserver:typed:<version>")
// Choose an engine for local development
implementation("com.lightningkite.lightningserver:engine-ktor:<version>")
// In-process engine for unit tests
testImplementation("com.lightningkite.lightningserver:engine-local:<version>")
}
Replace <version> with the version shown in the nightly badge at the top of
this file. The group ID is com.lightningkite.lightningserver; artifact IDs
match the module directory names above.
See LICENSE.txt.
TerraformAwsServerlessBuilder subclass reads your service settings and
emits .tf.json files for Lambda, API Gateway, S3, DynamoDB, MongoDB Atlas,
CloudWatch alarms, and more. The Terraform configuration is derived, not
hand-written.SERVER.test {} starts an ephemeral
in-process runtime; endpoint.test(auth, input) returns typed output
directly. No Docker, no ports, no external services needed.| Chapter | What it covers |
|---|
| Your First Endpoint | ServerBuilder, HttpHandler, HttpResponse, running your first test |
| Routing & Path Parameters | Nested paths, all HTTP methods, typed path args, sub-builders, query params |
| Typed Endpoints, Errors & SDK Generation | ApiHttpHandler, LSError, errorCases, success codes, SDK generation |
| Services & Settings | Declaring and swapping service settings; in-process RAM mocks for tests |
| Database & the Query DSL | Type-safe condition {} / modification {} DSL, @GenerateDataClassPaths, CRUD |
| Authentication & Sessions | PrincipalType, User.require(), reading auth.id / auth.fetch() in handlers |
| Testing Your Server | SERVER.test {}, HttpHandler.test(), ApiHttpHandler.test(auth, input), @Test |
| Deploying to AWS | AwsAdapter, TerraformAwsServerlessBuilder, service → Terraform, deploy workflow |
| Module | Purpose |
|---|
core / core-shared | Base HTTP types, routing, settings, serialization |
typed / typed-shared | Typed ApiHttpHandler, OpenAPI spec, SDK generation |
auth / auth-shared | PrincipalType, AuthRequirement, token handling |
sessions* | Pre-built session flows: email magic link, SMS PIN, OAuth, OpenID |
files / files-shared | File upload/download with S3, Azure, and local backends |
media / media-shared | Image processing |
engine-local | In-process engine for unit testing |
engine-ktor | Ktor-based HTTP server (Netty or CIO) |
engine-netty | Standalone Netty HTTP server |
engine-jdk-server | Pure JDK HTTP server |
engine-aws-serverless | AWS Lambda handler (AwsAdapter) + Terraform generation |
secret-source-aws | AWS Secrets Manager integration for deployment secrets |
demo | Reference implementation and integration test bed |
docs-guide | Compiled-sample documentation harness |
Surfaced from shared tags and platforms — no rankings paid for.