keii.dev
1<h1 align="center">Lustre Dev Tools</h1>
2
3<div align="center">
4 Lustre's official CLI and development tooling.
5</div>
6
7<br />
8
9<div align="center">
10 <a href="https://hex.pm/packages/lustre_dev_tools">
11 <img src="https://img.shields.io/hexpm/v/lustre_dev_tools"
12 alt="Available on Hex" />
13 </a>
14</div>
15
16<div align="center">
17 <h3>
18 <a href="https://hexdocs.pm/lustre">
19 Lustre
20 </a>
21 <span> | </span>
22 <a href="#commands">
23 Commands
24 </a>
25 <span> | </span>
26 <a href="https://discord.gg/Fm8Pwmy">
27 Discord
28 </a>
29 </h3>
30</div>
31
32<div align="center">
33 <sub>Built with ❤︎ by
34 <a href="https://twitter.com/hayleighdotdev">Hayleigh Thompson</a> and
35 <a href="https://twitter.com/giacomo_cava">Giacomo Cavalieri</a>
36</div>
37
38---
39
40## Features
41
42- Built-in **development server**.
43
44- Automatic detection and support for **TailwindCSS**.
45
46- **Bundle** and **minify** Lustre applications.
47
48- Distribute reusable **Web Components** for use outside of Gleam and Lustre.
49
50## Philosophy
51
52Lustre's dev tools are designed to make the experience as simple as possible for
53folks unfamiliar with frontend development or are exhausted at the state of
54JavaScript tooling. That means being opinionated about the tools we support and
55the commands we provide.
56
57If you find yourself needing more configuration or control over your build process,
58you might be outgrowing what Lustre's dev tools have set out to provide! We'd love
59to hear from those users too, though, so please open an issue or reach out on Discord
60if you think something is missing.
61
62For more advanced users, we recommend using [vite](https://vitejs.dev) and the
63[vite-gleam](https://github.com/Enderchief/gleam-tools/tree/master/packages/vite-gleam)
64package.
65
66## Installation
67
68Lustre's dev tools are published on [Hex](https://hex.pm/packages/lustre_dev_tools)!
69You can add them as a dev dependency to your Gleam projects from the command line:
70
71> **Note**: currently one of lustre_dev_tools' dependencies is not compatible with
72> the most recent version of `gleam_json`, making it impossible to install. To fix
73> this, add `gleam_json = "1.0.1"` as a dependency in your `gleam.toml` file.
74
75```sh
76gleam add lustre_dev_tools --dev
77```
78
79The `--dev` flag is important to make sure the dev tools are not included in your
80application's build!
81
82> **Note**: The included development server uses the erlang package [`fs`](https://github.com/5HT/fs)
83> as a file watcher. For Linux uses, you need to have [inotify-tools](https://github.com/inotify-tools/inotify-tools)
84> installed on your system. Both Linux and MacOS users must also have a C compiler.
85
86To run any of the commands provided by the dev tools, you should run the
87`lustre/dev` module using Gleam's `run` command:
88
89```sh
90gleam run -m lustre/dev build app
91```
92
93## Commands
94
95You can run `gleam run -m lustre/dev -- --help` to see a list of all the available
96commands. Each command also has its own help text that lists the available flags
97and options. Here's a brief overview of the commands provided by Lustre's dev tools:
98
99- `lustre/dev add` - Commands for adding external binaries to your project. These
100 are run and managed by Lustre, and while not typically intended to be run manually,
101 they can be found inside `build/.lustre/bin`.
102
103 - `lustre/dev add esbuild` - Download a platform-appropriate version of the
104 esbuild binary. Lustre uses this to bundle applications and act as a development
105 server, and will automatically download the binary if either the `build` or
106 `start` commands are run.
107
108 - `lustre/dev add tailwind` - Download a platform-appropriate version of the
109 Tailwind binary. Lustre will automatically use this to compile your styles if
110 it detects a `tailwind.config.js` in your project but will not download it
111 automatically. Be sure to add the following to your root level `index.html`
112
113 `<link rel="stylesheet" type="text/css" href="/priv/static/my_app.css" />`
114
115- `lustre/dev build` - Commands to build different kinds of Lustre application.
116 These commands go beyond just running `gleam build` and handle features like
117 bundling, minification, and integration with other build tools.
118
119 - `lustre/dev build app` - Build and bundle an entire Lustre application. The
120 generated JavaScript module calls your app's `main` function on page load and
121 can be included in any Web page without Gleam or Lustre being present.
122
123 - `lustre/dev build component` - Build a Lustre component as a portable Web
124 Component. The generated JavaScript module can be included in any Web page
125 and used without Gleam or Lustre being present.
126
127- `lustre/dev start` - Start a development server for your Lustre project. This
128 command will compile your application and serve it on a local server. If your
129 application's `main` function returns a compatible `App`, this will generate
130 the necessary code to start it. Otherwise, your `main` function will be used
131 as the entry point.
132
133## Support
134
135Lustre is mostly built by just me, [Hayleigh](https://github.com/hayleigh-dot-dev),
136around two jobs. If you'd like to support my work, you can [sponsor me on GitHub](https://github.com/sponsors/hayleigh-dot-dev).
137
138Contributions are also very welcome! If you've spotted a bug, or would like to
139suggest a feature, please open an issue or a pull request.