Datastar Gleam SDK

A Gleam implementation of the Datastar SDK with first-class integrations for Mist, Wisp, and Lustre.

What is Datastar?

Datastar is a hypermedia framework that uses Server-Sent Events (SSE) to push DOM patches and state updates from the server to the browser. You write standard HTML on the backend and Datastar takes care of reactive updates on the frontend — no custom JavaScript required.

This library gives you everything you need to produce and consume Datastar messages from Gleam:

Module	Purpose
`datastar_gleam`	Core `DatastarEvent` type and SSE wire-format serializer.
`datastar_gleam/consts`	Constants, `EventType`, and `ElementPatchMode`.
`datastar_gleam/event`	Builders for `PatchElements`, `PatchSignals`, and `ExecuteScript`.
`datastar_gleam/mist`	Stream events via Mist's built-in SSE support.
`datastar_gleam/wisp`	Read incoming Datastar signals from Wisp requests.
`datastar_gleam/lustre`	Generate Datastar HTML attributes for Lustre views.

Installation

gleam add datastar_gleam

Quick Start

1. Build events with `datastar_gleam/event`

import datastar_gleam/event

let patch =
  event.new_elements("<div id='message'>Hello!</div>")
  |> event.with_selector("#target")
  |> event.with_mode(event.Append)

let ev = event.patch_elements_to_datastar_event(patch)

2. Stream events over Mist SSE

import datastar_gleam/event
import datastar_gleam/mist as datastar_mist
import mist

mist.server_sent_events(
  request: req,
  initial_response: response.new(200),
  init: fn(subject) { #(subject, 0) },
  loop: fn(state, _msg, conn) {
    let patch = event.new_elements("<div>Updated!</div>")
    let ev = event.patch_elements_to_datastar_event(patch)
    let _ = datastar_mist.send_event(conn, ev)
    actor.continue(state)
  },
)

3. Read signals from Wisp requests

import datastar_gleam/wisp as datastar_wisp
import gleam/dynamic/decode

let decoder = decode.at(["delay"], decode.int)
case datastar_wisp.read_signals(req, decoder) {
  Ok(signals) -> // use signals
  Error(datastar_wisp.MissingHeader) -> // not a datastar request
}

4. Generate Datastar attributes in Lustre

import datastar_gleam/lustre as datastar
import lustre/element/html

html.button(
  [datastar.on_get("/hello-world")],
  [html.text("Start")],
)

Detailed Usage

Patching Elements

PatchElements is the most common event type. It tells the browser to insert, replace, or remove HTML.

import datastar_gleam/event

// Replace the inner HTML of #message
let patch =
  event.new_elements("<p>Hello, world!</p>")
  |> event.with_selector("#message")
  |> event.with_mode(event.Inner)

let ev = event.patch_elements_to_datastar_event(patch)

Available patch modes:

Mode	Behaviour
`Outer`	Replace the outer HTML of the matched element (default).
`Inner`	Replace the inner HTML of the matched element.
`Append`	Insert after the last child.
`Prepend`	Insert before the first child.
`Before`	Insert immediately before the matched element.
`After`	Insert immediately after the matched element.
`Replace`	Replace the matched element entirely.
`Remove`	Remove the matched element from the DOM.

Patching Signals

Signals are Datastar's reactive data store. You can push new values from the server:

import datastar_gleam/event

let patch =
  event.new_signals("{ \"count\": 42 }")
  |> event.with_only_if_missing(True)

let ev = event.patch_signals_to_datastar_event(patch)

Executing Scripts

You can also inject and run arbitrary JavaScript:

import datastar_gleam/event

let script =
  event.new_script("console.log('Hello from Gleam!')")
  |> event.with_auto_remove(True)

let ev = event.execute_script_to_datastar_event(script)

Serialising Events

If you need the raw SSE text (for example, to write your own transport):

import datastar_gleam

let text = datastar.to_string(ev)
// => event: datastar-patch-elements
//    data: selector #target
//    data: mode append
//    data: elements <div>Updated!</div>
//

Examples

Two runnable examples are included in the repository:

`examples/hello_world`

A minimal Mist server that streams a typewriter effect via SSE.

cd examples/hello_world
gleam run
# open http://localhost:3000

`examples/lustre_ssr`

A Lustre SSR app that renders the initial page with Datastar attributes and then streams updates over Mist SSE.

cd examples/lustre_ssr
gleam run
# open http://localhost:3001

Full API Reference

See HexDocs for the complete API reference, including all types and functions.

Licence

MIT