Lustre

Features

• A declarative, functional API for constructing HTML. No templates, no macros, just Gleam.

• An Erlang and Elm-inspired architecture for managing state.

• Managed side effects for predictable, testable code.

• Universal components that enable "write once, run anywhere"" code. Lustre applications can be mounted onto elements on a page, built and distributed as Web Components, or run as interactive Server Components.

• A batteries-included CLI that lets you develop and build Lustre applications without managing a JavaScript runtime.

Example

Lustre comes with over 20 examples! Here's what it looks like:

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

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

  Nil
}

type Model
  = Int

fn init(_flags) -> Model {
  0
}

type Message {
  UserClickedIncrement
  UserClickedDecrement
}

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

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(" - ")
    ])
  ])
}

Philosophy

Lustre is an opinionated library for building frontend Web applications. Modern frontend development is hard and complex. Some of that complexity is necessary, but a lot of it is accidental or comes from having far too many options. Lustre has the same design philosophy as Gleam: where possible, there should be only one way to do things!

That means shipping with a single state management system out of the box, modelled after Elm and Erlang/OTP. Open any Lustre application and you should feel right at home.

It also means we encourage simple approaches to constructing views over complex ones. Lustre does have a way to create encapsulated stateful components (something we sorely missed in Elm) but it shouldn't be the default. Prefer simple functions to stateful components.

Where components are necessary, lean into the fact that Lustre components can run anywhere. Lustre gives you the tools to write components that can run inside an existing Lustre application, export them as a standalone Web Component, or run them on the server with a minimal runtime for patching the DOM. Lustre calls these universal components and they're written with Gleam's multiple targets in mind.

Installation

Lustre is published on Hex! You can add it to your Gleam projects from the command line:

gleam add lustre

Lustre also has a companion package containing development tooling that you might like to install:

gleam add --dev lustre_dev_tools

Where next

To get up to speed with Lustre, check out the quickstart guide. If you prefer to see some code, the examples directory contains a handful of small applications that demonstrate different aspects of the library.

You can also read through the documentation and API reference on HexDocs.

Support

Lustre is mostly built by just me, Hayleigh, around two jobs. If you'd like to support my work, you can sponsor me on GitHub.

Contributions are also very welcome! If you've spotted a bug, or would like to suggest a feature, please open an issue or a pull request.