lustre/dev

Lustres Dev Tools is a CLI (Command Line Interface) that provides a set of commands for running and building Lustre projects. If you’re familiar with frontend Web development, you could consider the Lustre Dev Tools as something similar to vite but built right into the framework! If you’re not familiar with what these tools are used for… then read on.

Lustre Dev Tools is written in Gleam and requires Erlang to be installed even if you are only building a JavaScript project. Most methods of installing Gleam will guide you through installing Erlang too, but make sure you have it installed before you try to use the Lustre CLI!

Because the CLI is written in Gleam, you will run it using the gleam command. As an example, starting a development server looks like this:

gleam run -m lustre/dev start

lustre/dev add

This command lets you install development-specific binaries and tools from outside the Gleam ecosystem. Lustre tries to be smart about the executables it understands: if you try to build a project without esbuild it will grab it, if it finds a tailwind.config.js it will use tailwind, and so on. All binaries are added to build/.lustre/bin in case you need to execute them manually.

`lustre/dev add esbuild`

Esbuild is a bundler and build tool for JavaScript projects. This is the backbone of a lot of Lustre’s build tooling and will be installed automatically if you use lustre build or lustre dev.

Example:

gleam run -m lustre/dev add esbuild

`lustre add tailwind`

Tailwind CSS is a utility-first CSS framework popular among devs that want to quickly iterate on designs without touching CSS directly. This will be installed automatically if Lustre detects a tailwind.config.js file in your project.

Example:

gleam run -m lustre/dev add tailwind

lustre/dev build

Gleam projects can be compiled to JavaScript but this output is not always desirable for frontend projects where many individual modules can cause HTTP bottlenecks and slower load times. The lustre build command produces different bundles that are single JavaScript files containing all the code needed for an application to run.

If a lustre build subcommand is run without the necessary tooling installed, Lustre will attempt to install it automatically.

`lustre/dev build app`

Bundle a Gleam application into a single JavaScript file. This requires a Gleam module in your project with the same name as the project itself, and a public main function that will be called when the application starts.

This can be any Gleam program, but if your main function returns an App(Nil, model, msg) then Lustre will automatically generate some boilerplate to mount the app onto an element with the id "app" and start it.

Flags:

--minify - Reduce the size of the output bundle by removing whitespace and renaming variables. This is useful for production builds.

Example:

gleam run -m lustre/dev build app

`lustre/dev build component`

Lustre components are based on standard Web Components. This means they should be usable outside of Lustre and Gleam! The lustre build component command takes a module and bundles it into a single JavaScript file that can be included in any Web app to register a new Custom Element that can be used like native HTML elements.

For a module to be bundled as a component, it must adhere to the following rules:

There must be a pub const name that is a string representing the name of the component to register. Remember that it must always contain a hyphen and follow these rules.
There must be a pub fn that has the type fn() -> App(Nil, model, msg). It’s name is not important but in cases where multiple functions in a module fit this type, the first one will be used.

Arguments:

<module_path> - The path to the Lustre component you want to bundle. This should be in the same format that you would write to import the module in a Gleam file, e.g. ui/my_componnt and not src/ui/my_component.gleam.

Flags:

--minify - Reduce the size of the output bundle by removing whitespace and renaming variables. This is useful for production builds.

Example:

gleam run -m lustre/dev build component ui/counter

lustre/dev start

The lustre/dev start command starts a development server that builds and serves your project. This lets you focus on development without having to worry about a backend or additional tooling.

Currently the server does not watch for changes to your Gleam source files. You must restart the server for changes to take effect. There have been discussions about including a watch command in the Gleam compiler that would make this possible.

Flags:

--port - The port to serve the project on. Defaults to 1234.
--host - The host to serve the project on. Defaults to 0.0.0.0 and is accessible on localhosts and any other devices on the same network.
--html - Provide a custom HTML file to serve. This is useful if you want to include your own styles or scripts.

To make sure the Lustre bundle can be loaded, you must include the following script tag somewhere in your HTML file:
```
<script type="application/lustre"></script>
```
--use-example-styles - Include the stylesheet from lustre/ui. This is mainly used in the example projects, but you may use this option to quickly experiment with the library yourself.

If the --html flag is provided, this flag will be ignored.

Example:

gleam run -m lustre/dev start --port=8080 --use-example-styles

Getting help

Lustre Dev Tools is still an experimental work in progress. If you run in to issues or have ideas for how it could be improved we’d love to hear from you, either by opening an issue or reaching out on the Gleam Discord server.

Functions

main

</>

pub fn main() -> Nil

The main function is used as the entry point for Lustre’s dev tools. You shouldn’t run this function in your code, but instead use Gleam run to run this module from the command line. To see what the dev tools can do, run:

gleam run -m lustre/dev -- --help