Lustre Frontend Counter and Form

The Elm Architecture

• Lustre brings the Elm architecture to Gleam with three parts:
  • Model: the application state, a plain record
  • Update: a pure function (Model, Msg) -> Model that handles every user action
  • View: a pure function Model -> Element(Msg) that produces a virtual DOM tree
• The Lustre runtime renders the view, listens for events, converts them to Msg values, calls update, re-renders, and repeats
• The application code never touches the DOM directly

Types

pub type Model {
  Model(count: Int)
}

pub type Msg {
  Increment
  Decrement
  Reset
}

• Model(count: Int) is the entire application state
• Msg lists every action the user can take: Increment, Decrement, Reset
• Adding a new feature means adding a variant to Msg and a branch to update
  • The compiler flags every case that is not handled

Update

pub fn update(model: Model, msg: Msg) -> Model {
  case msg {
    Increment -> Model(model.count + 1)
    Decrement -> Model(model.count - 1)
    Reset -> Model(0)
  }
}

• Each branch returns a new Model with the count changed
• No mutation: Model(model.count + 1) creates a new record

View

• In a browser application, view returns Lustre's Element(Msg) type:

fn view(model: Model) -> Element(Msg) {
  html.div([], [
    html.p([], [html.text(int.to_string(model.count))]),
    html.button([event.on_click(Increment)], [html.text("+")]),
    html.button([event.on_click(Decrement)], [html.text("-")]),
    html.button([event.on_click(Reset)],     [html.text("reset")]),
  ])
}

• html.div(attrs, children) mirrors <div>...</div>
• event.on_click(Increment) attaches a click listener that sends Increment to update
• html.text renders a string as a text node
• The return type Element(Msg) guarantees that every event this tree can fire is a valid Msg

Console Demo

  let model = init()
  let model = update(model, Increment)
  let model = update(model, Increment)
  let model = update(model, Decrement)
  io.println(view(model))

• The demo runs without a browser to confirm the model-update-view logic in isolation
• init() creates a Model(count: 0)
• After two increments and one decrement, model.count is 1
• view(model) returns "Count: +1 (click + or - to change)"

Running in the Browser

• To run in the browser:
  1. Add lustre to gleam.toml dependencies
  2. Set target = "javascript" in gleam.toml
  3. Replace the console view with an HTML view returning Element(Msg)
  4. Call lustre.simple(init, update, view) in main

pub fn main() {
  let app = lustre.simple(init, update, view)
  let assert Ok(_) = lustre.start(app, "#app", Nil)
}

• "#app" is the CSS selector for the DOM element Lustre mounts into

Handling Forms

• A more complex model adds an input field and a list of items:

type Model {
  Model(count: Int, input: String, items: List(String))
}

type Msg {
  Increment
  Decrement
  Reset
  InputChanged(String)
  AddItem
  RemoveItem(Int)
}

• InputChanged(String) fires on every keystroke
  • update stores the new string in model.input
• AddItem moves model.input into model.items and clears the input
• The view renders an <input> with event.on_input(InputChanged) and an Add button with event.on_click(AddItem)
• This pattern extends to any form
  • Bind each field to a Msg variant
  • Store it in the model
  • Submit on a button click

Connecting to an API

• Lustre effects run IO outside the pure update function:

fn fetch_todos() -> effect.Effect(Msg) {
  effect.from(fn(dispatch) {
    // make HTTP request, then:
    dispatch(TodosLoaded(todos))
  })
}

• effect.from wraps an IO action; the dispatch callback sends a Msg back when the action completes
• update returns #(Model, Effect(Msg)) when effects are used
• The runtime runs the effect after rendering
• This keeps the model and update function pure: side effects are explicitly separated

Testing

pub fn increment_test() {
  init()
  |> update(Increment)
  |> update(Increment)
  |> fn(m) { m.count }
  |> should.equal(2)
}

pub fn decrement_test() {
  init()
  |> update(Decrement)
  |> fn(m) { m.count }
  |> should.equal(-1)
}

pub fn reset_test() {
  let model = update(init(), Increment) |> update(Increment)
  update(model, Reset).count
  |> should.equal(0)
}

• The update function is pure, so testing it requires no browser
• increment_test chains two increments and checks model.count
• decrement_test confirms decrement goes negative
• reset_test confirms Reset always returns count to 0

Check Understanding

Exercises