# Datastar Gleam SDK
[](https://hex.pm/packages/datastar_gleam)
[](https://hexdocs.pm/datastar_gleam/)
A Gleam implementation of the [Datastar](https://data-star.dev) SDK with first-class integrations for [Mist](https://hexdocs.pm/mist), [Wisp](https://hexdocs.pm/wisp), and [Lustre](https://hexdocs.pm/lustre).
## What is Datastar?
[Datastar](https://data-star.dev) 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`](https://hexdocs.pm/datastar_gleam/datastar_gleam.html) | Core `DatastarEvent` type and SSE wire-format serializer. |
| [`datastar_gleam/consts`](https://hexdocs.pm/datastar_gleam/datastar_gleam/consts.html) | Constants, `EventType`, and `ElementPatchMode`. |
| [`datastar_gleam/event`](https://hexdocs.pm/datastar_gleam/datastar_gleam/event.html) | Builders for `PatchElements`, `PatchSignals`, and `ExecuteScript`. |
| [`datastar_gleam/mist`](https://hexdocs.pm/datastar_gleam/datastar_gleam/mist.html) | Stream events via Mist's built-in SSE support. |
| [`datastar_gleam/wisp`](https://hexdocs.pm/datastar_gleam/datastar_gleam/wisp.html) | Read incoming Datastar signals from Wisp requests. |
| [`datastar_gleam/lustre`](https://hexdocs.pm/datastar_gleam/datastar_gleam/lustre.html) | Generate Datastar HTML attributes for Lustre views. |
---
## Installation
```sh
gleam add datastar_gleam
```
---
## Quick Start
### 1. Build events with `datastar_gleam/event`
```gleam
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
```gleam
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
```gleam
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
```gleam
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.
```gleam
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:
```gleam
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:
```gleam
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):
```gleam
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.
```sh
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.
```sh
cd examples/lustre_ssr
gleam run
# open http://localhost:3001
```
---
## Full API Reference
See [HexDocs](https://hexdocs.pm/datastar_gleam/) for the complete API reference, including all types and functions.
---
## Licence
MIT
