lightspeed - v1.1.0

Gleam Lightspeed

Lightspeed is a production-ready, LiveView-style web framework for Gleam.

Build server-rendered, stateful, realtime interfaces in Gleam without splitting core logic across a separate frontend framework.

Lightspeed is designed for teams that need strong runtime guarantees, typed application contracts, and operational control on the BEAM.

Lightspeed uses Gleam’s strengths:

Why Lightspeed

Status

1.0.0 parity GA is complete through M20. Post-GA competitive hardening is complete through M60. Production-readiness certification is enforced by make production-ready.

Historical 0.1.0-rc references:

GA references:

Install

gleam add lightspeed

Quick start

import lightspeed
import lightspeed/component

pub fn index_markup() -> String {
  let rendered = component.html("<h1>" <> lightspeed.banner() <> "</h1>")
  component.to_html(rendered)
}

Generate local API docs with make docs, then open build/dev/docs/lightspeed/index.html.

Runtime model

A Lightspeed live view is a server-owned state machine:

  1. The first request returns static HTML.
  2. The browser connects over a live transport, normally WebSocket.
  3. A per-session server process owns state.
  4. Browser events are decoded into typed messages.
  5. Application state is updated.
  6. A render pass produces a new HTML tree or fragment.
  7. Lightspeed sends a patch instruction to the client.
  8. The client applies the patch and acknowledges it.

Repository layout

.
├── src/                    # Gleam library modules
│   └── lightspeed/
│       ├── agent/           # typestate + ISA agents
│       ├── component.gleam  # component contract
│       ├── component/       # helpers + stateful/template/story APIs
│       ├── diff.gleam       # patch model
│       ├── event.gleam      # typed event decoders
│       ├── form.gleam       # form bindings
│       ├── framework/       # endpoint/controller/verified-routes layer
│       ├── ops/             # production hardening helpers
│       ├── channel.gleam    # channel routing core
│       ├── presence.gleam   # presence diff tracker
│       ├── protocol.gleam   # wire frame model
│       ├── pubsub.gleam     # pubsub fanout abstraction
│       ├── router.gleam     # router integration layer
│       ├── pipeline.gleam   # ETL pipeline lifecycle contracts
│       ├── pipeline/        # checkpoint + telemetry + quality + SLO ETL contracts
│       └── transport.gleam  # transport abstraction
├── test/                   # gleeunit tests
├── client/                 # browser runtime + JS command layer
├── docs/                   # design docs and developer docs
├── specs/                  # normative specifications
├── rfcs/                   # change proposals
├── adrs/                   # architecture decision records
├── examples/               # example applications and API usage
├── Makefile
└── gleam.toml

Core concepts

Developer ergonomics (Phase 6)

Application-facing helpers are available in:

See examples/crud/README.md for an end-to-end typed flow combining route matching, event decoding, form bindings, and command helpers.

Production hardening (Phase 7)

Operational helper modules:

Deployment and security guidance:

Realtime compatibility (Phase 14)

Channel-focused modules:

Component/template compatibility (Phase 15)

Component-focused modules:

Migration examples:

Client JS compatibility (Phase 16)

Client runtime command surface:

Interop examples and notes:

LiveView-style test DSL compatibility (Phase 17)

Testing-focused module:

Migration examples:

Generator tooling compatibility (Phase 25)

Generator modules:

M25 depth additions:

Generator docs:

Data/domain migration compatibility (Phase 19)

Data and migration modules:

Migration/operator docs:

Ecosystem integration compatibility (Phase 26)

Integration modules:

M26 additions:

Integration docs:

Durable cluster failover compatibility (Phase 27)

Failover modules:

M27 additions:

Failover docs:

Large data + async backpressure compatibility (Phase 28)

M28 modules:

M28 additions:

M28 docs:

Tenant isolation and policy runtime compatibility (Phase 29)

M29 modules:

M29 additions:

M29 docs:

Chaos/fuzz and SLO autopilot gate (Phase 30)

M30 modules:

M30 additions:

M30 docs:

Integrated data pipeline core (Phase 31)

M31 modules:

M31 additions:

M31 docs:

Connector and orchestration parity (Phase 32)

M32 modules:

M32 additions:

M32 docs:

ETL reliability and SLO gate (Phase 33)

M33 modules:

M33 additions:

M33 docs:

Production load benchmark suite (Phase 34)

M34 module:

M34 additions:

M34 docs:

Runtime hot-path optimization suite (Phase 35)

M35 module:

M35 additions:

M35 docs:

Render churn reduction for high-frequency views (Phase 36)

M36 modules:

M36 additions:

M36 docs:

Durable store contention profiling for clusters (Phase 37)

M37 modules:

M37 additions:

M37 docs:

App platform parity foundations (Phase 38)

M38 modules:

M38 additions:

M38 docs:

HTML/template ergonomics and productivity parity (Phase 39)

M39 modules:

M39 additions:

M39 docs:

Tenant isolation and policy runtime expansion (Phase 52)

M52 modules:

M52 additions:

M52 docs:

Chaos and fault-injection verification harness expansion (Phase 53)

M53 modules:

M53 additions:

M53 docs:

Operational autopilot and SLO-aware controls expansion (Phase 54)

M54 modules:

M54 additions:

M54 docs:

First-class nested LiveView lifecycle primitives (Phase 55)

M55 modules:

M55 additions:

M55 docs:

Transport compatibility and progressive enhancement model expansion (Phase 56)

M56 modules:

M56 additions:

M56 docs:

ORM/data ergonomics parity profile (Phase 57)

M57 modules:

M57 additions:

M57 docs:

Turnkey app platform defaults and presets (Phase 58)

M58 modules:

M58 additions:

M58 docs:

Developer tooling polish and productivity suite (Phase 59)

M59 modules:

M59 additions:

M59 docs:

Integrated data pipelines and ETL runtime operations surface (Phase 60)

M60 modules:

M60 additions:

M60 docs:

Parity GA policy (Phase 20)

GA policy modules:

Verified routes hard parity (Phase 22)

Verified routes modules:

Migration guide:

Template compiler parity (Phase 23)

Template compiler modules:

Migration guide:

Transport matrix parity (Phase 24)

Transport matrix modules:

Compatibility/migration guide:

Live component

A component is modeled as pure update/render logic plus explicit commands.

pub type Component(model, msg) {
  Component(
    init: fn() -> model,
    update: fn(model, msg) -> #(model, List(Command(msg))),
    render: fn(model) -> Rendered,
  )
}

Typestate agent

The connection lifecycle is represented with phantom types. Invalid lifecycle transitions should fail at compile time.

let agent = typestate.new("session-1")
let agent = typestate.handshake(agent)
let agent = typestate.mount(agent)
let agent = typestate.go_live(agent)

A function that requires Agent(Live) cannot receive Agent(Disconnected).

Orthogonal ISA

The Lightspeed ISA is a small instruction set that describes runtime effects independently of transport, HTTP server, renderer, or browser implementation.

Examples:

The same ISA can be interpreted by:

Local development

Prerequisites:

make setup
make ci

Useful targets:

make fmt
make check
make test
make test-client
make docs
make channel-report
make integration-fixture
make failover-fixture
make large-data-fixture
make tenant-fixture
make chaos-fixture
make chaos-expansion-fixture
make operational-autopilot-fixture
make nested-lifecycle-fixture
make transport-expansion-fixture
make data-ergonomics-fixture
make pipeline-fixture
make connector-fixture
make etl-fixture
make etl-budget
make hot-path-fixture
make render-churn-fixture
make contention-fixture
make app-platform-fixture
make template-ergonomics-fixture
make operations-kit-fixture
make adapter-sdk-fixture
make replay-diagnostics-fixture
make protocol-contract-fixture
make ai-workflow-fixture

Ecosystem interoperability

Lightspeed integrates with existing Gleam ecosystem tools. Wisp/Mist can serve HTTP and WebSocket infrastructure, Lustre can inform rendering strategy, and gleam_otp provides the actor substrate.

Lightspeed’s focus is the LiveView-style runtime contract: typed events, stateful sessions, lifecycle safety, deterministic patch delivery, and operational certification.

Versioning

As of 1.0.0, the public API and protocol are stable under semantic versioning. Breaking changes require a major version and documented migration notes.

Planned compatibility boundaries:

License

Lightspeed is distributed under The Unlicense. See LICENSE.md.

✨ Search Document