Lustre Documentation

In Lustre, a component is a stateful, nested Model-View-Update application. While available, they should not be the default. Instead, use view functions: stateless functions that return Elements.

Why prefer view functions?

• Intentional State: View functions only take arguments, forcing you to be deliberate about what state is actually needed.
• Better Organization: Keeps code grouped by what it does rather than what it is, following idiomatic Gleam/Elm patterns.
• Easier Testing: Plain view functions and data transformation functions are much easier to test with standard Gleam tools than encapsulated components.
• Simpler Refactoring: Since state is managed higher up the tree rather than being tightly coupled inside a component, moving UI elements around is less painful.
• Less Boilerplate: Components require defining an init, update, view, Model, and Message type, which adds significant overhead for simple UI tasks.

Lustre does not have a built-in hydration mechanism, but you can implement it by ensuring the server-rendered HTML and the client-side initial model are synchronized.

The Pattern:

1. Server-side: Render the application's view using the initial model. Serialize that initial model into a JSON string and embed it in the HTML (e.g., inside a <script> tag with a specific ID).
2. Client-side: Use a browser API (via a package like plinth) to read the JSON from the script tag, decode it into the initial model, and pass it as flags to lustre.start.

// 1. Server-side: Embedding the model in HTML
// <script type="application/json" id="model">5</script>

// 2. Client-side: Reading flags and starting the app
import gleam/json
import gleam/result
import lustre
import plinth/browser/document
import plinth/browser/element

pub fn main() {
  let json_text = 
    document.query_selector("#model")
    |> result.map(element.inner_text)

  let flags = 
    case json.parse(json_text, decode.int) {
      Ok(count) -> count
      Error(_) -> 0
    }

  let app = lustre.application(init, update, view)
  let assert Ok(_) = lustre.start(app, "#app", flags)
}

Lustre applications are built using the Model-View-Update (MVU) architecture, which implements a unidirectional data flow:

• Model: A single, immutable data structure that describes the entire state of your application at a given point in time.
• View: A pure function of the model. If the model does not change, the UI does not change.
• Update: A function that receives messages (events from the outside world like user interactions or HTTP responses) and constructs a new model.

This approach provides a single source of truth, declarative state updates, and pure state transitions that are easy to test.

                                       +--------+
                                       |        |
                                       | update |
                                       |
                                       +--------+
                                         ^    |
                                         |    |
                                 Message |    | Model
                                         |    |
                                         |    v
+------+                         +------------------------+
|      |          Model          |                        |
| init |------------------------>|     Lustre Runtime     |
|      |                         |                        |
+------+                         +------------------------+
                                         ^    |
                                         |    |
                                 Message |    | Model
                                         |    |
                                         |    v
                                       +--------+
                                       |        |
                                       |  view  |
                                       |
                                       +--------+

Lustre applications are built using a message-based state management system (similar to the Elm Architecture). Every interactive application is composed of three core building blocks:

1. Model: A type representing the entire state of your application. An init function is used to construct the initial model.
2. Message: A type representing all possible ways the outside world (e.g., user interactions, API responses) can communicate with your application. An update function receives these messages and returns a new Model.
3. View: A function that takes the current Model and returns an Element(Message). This function is called whenever the model changes to re-render the UI.

The Lifecycle Loop: Model $\rightarrow$ view $\rightarrow$ Element(Message) $\rightarrow$ (User Interaction) $\rightarrow$ Message $\rightarrow$ update $\rightarrow$ New Model $\rightarrow$ (Repeat)

import gleam/int
import lustre
import lustre/element.{type Element}
import lustre/element/html
import lustre/event

// 1. The Model
type Model = Int

// 2. The Messages
type Message {
  UserClickedIncrement
  UserClickedDecrement
}

// The init function
fn init(_args) -> Model {
  0
}

// The update function
fn update(model: Model, message: Message) -> Model {
  case message {
    UserClickedIncrement -> model + 1
    UserClickedDecrement -> model - 1
  }
}

// 3. The View
fn view(model: Model) -> Element(Message) {
  let count = int.to_string(model)

  html.div([], [
    html.button([event.on_click(UserClickedIncrement)], [html.text("+")]), 
    html.p([], [html.text(count)]),
    html.button([event.on_click(UserClickedDecrement)], [html.text("-")])
  ])
}

pub fn main() {
  // Use lustre.simple to tie the blocks together
  let app = lustre.simple(init, update, view)
  let assert Ok(_) = lustre.start(app, "#app", Nil)
  Nil
}