lib-humus 0.6.0

Helps creating configurable frontends for humans and computers using axum, Tera and toml.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

<!--
SPDX-FileCopyrightText: 2026 Slatian <baschdel@disroot.org>

SPDX-License-Identifier: AGPL-3.0-or-later
-->

# lib-humus 🌱

[Codeberg](https://codeberg.org/slatian/lib-humus/) | [Documentation](https://docs.rs/lib-humus)

Helps creating frontends for humans and computers using axum, [Tera](https://keats.github.io/tera/), [Fluent](https://projectfluent.org/) and toml.

[Documentation](https://docs.rs/crate/lib-humus) | [Codeberg](https://codeberg.org/slatian/lib-humus)

Update for version 0.6: This is a big one, see the migration guide in the doc module.

> Where does the name come from?

It's something to grow new projects on and it includes ter(r)a, so humus it is.

## What does it do?

### Render Templates

The `HumusEngine` uses Tera and the axum framework to produce http responses with minimal code overhead in the main logic. It is able to serve both a UI and an API from one datastructure.

You can also hook into the templating and register custom data and functions like you are used to.

### Translation

lib-humus automatically loads and hooks up project fluent templates to your regular tera templates so you can focus on translating instead of plumbing.

### Content Negotiation

lib-humus already knows about available templates and languages which means it can handle the `Accept` and `Accept-Language` headers for you.

## Examples

### barebones

This is a barebones example that shows how to start a server and hook up views using lib humus. It includes an index and a not found view, and a generic error view with bare minimum HTML templates.

How to run:
```sh
cd examples/barebones/
cargo run
```

By default the server will start on `http://localhost:1234`.

The error page is available on `http://localhost:1234/error`

The format can be switched using the `format` query parammeter, for example `https://localhost:1234/error?format=json` will return the following json output:
```json
{
	"kind": "index",
	"message":"This is an example of an error message."
}
```

The `kind` key is always set to the template name, other keys will be taken from the view datastructure using serde. This data is available inside the template on the `data` field. for example to make the template output its own name: `{{ data.kind }}`.

### barebones_localized

This is based on the `barebones` example and adds localization along with a language chooser, so you can ealily play around with the localization part.

How to run:
```sh
cd examples/barebones_localized/
cargo run
```


## Compatibility

Version compatibility:

| lib-humus | axum            | axum-extra              | tera |
|-----------|-----------------|-------------------------|------|
| 0.6       | [0.8][axum_0.8] | [0.12][axum_extra_0.12] | 2.1  |
| 0.5       | [0.8][axum_0.8] | [0.12][axum_extra_0.12] | 1    |
| 0.3 - 0.4 | [0.8][axum_0.8] | [0.10][axum_extra_0.10] | 1    |
| 0.2       | [0.7][axum_0.7] | -                       | 1    |
| 0.1       | 0.6             | -                       | 1    |

[axum_0.7]: https://github.com/tokio-rs/axum/releases/tag/axum-v0.7.0
[axum_0.8]: https://github.com/tokio-rs/axum/releases/tag/axum-v0.8.0
[axum_extra_0.10]: https://github.com/tokio-rs/axum/releases/tag/axum-extra-v0.10.0
[axum_extra_0.12]: https://github.com/tokio-rs/axum/releases/tag/axum-extra-v0.12.0

## License

This project is licensed under an [AGPL-3.0-or-later License](LICENSES/AGPL-3.0-or-later.txt) this is to ensure that it isn't used in proprietary software.

The examples are [CC0-1.0](LICENSES/CC0-1.0.txt) licensed, the intention is to make it clear that using those does not require attribution or keeping copyright notices intact.
This project recommends using the `AGPL-3.0-or-later` license for your applications.

This project is complaint with the [EUSE 3.3 specification](https://reuse.software/spec-3.3/).