nicd / lustre

An Elm-inspired framework for building HTML templates, single page applications, and server-rendered components in Gleam!

Lustre

✨ Make your frontend shine ✨

A framework for building Web apps in Gleam!

Quickstart | Reference | Discord

_{Built with ❤︎ by Hayleigh Thompson and contributors}

---

Table of contents

• Features
• Example
• Philosophy
• Installation
• Where next
• Support

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. Write once, run anywhere. Elm meets Phoenix LiveView.

• A batteries-included CLI that makes scaffolding and building apps a breeze.

• Server-side rendering for static HTML templating.

Example

import gleam/int
import lustre
import lustre/element.{text}
import lustre/element/html.{div, button, p}
import lustre/event.{on_click}

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

  Nil
}

fn init(_) {
  0
}

type Msg {
  Incr
  Decr
}

fn update(model, msg) {
  case msg {
    Incr -> model + 1
    Decr -> model - 1
  }
}

fn view(model) {
  let count = int.to_string(model)

  div([], [
    button([on_click(Incr)], [text(" + ")]),
    p([], [text(count)]),
    button([on_click(Decr)], [text(" - ")])
  ])
}

Philosophy

Lustre is an opinionated framework for building small-to-medium-sized 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 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

Note: this guide is written for Lustre v4, which is currently in release candidate status. To follow along with this guide, you need to manually edit your gleam.toml and change the required version of lustre to "4.0.0-rc.2".

If you're using a different build tool, like Rebar3 or Mix, you can add Lustre to your rebar.config or mix.exs file respectively.

{deps, [
  {lustre, "4.0.0"}
]}

defp deps do
  [
    {:lustre, "~> 4.0"}
  ]
end

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 framework.

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.