tmk241
95 lines
3.1 KiB
Markdown
95 lines
3.1 KiB
Markdown
# Hemx
|
|
|
|
Hemx is checked hypermedia for Rust. Applications render Hemplate views, handle
|
|
events in typed Rust functions, and return generated UI effects. The browser runs
|
|
a small effect interpreter instead of a virtual DOM, hydration framework, or
|
|
client-side expression language. The same core compiles for native servers and
|
|
server-side Wasm isolates; platform storage, sockets, and lifecycle remain
|
|
application concerns.
|
|
|
|
## How it works
|
|
|
|
1. `.heml` templates declare page roots, slots, forms, handles, and keyed targets.
|
|
2. `hemx-build` generates typed Rust helpers from that surface.
|
|
3. `#[hemx::handler]` functions accept ordinary Rust inputs and return typed effects.
|
|
4. `hemx-axum` serves pages, assets, handler routes, and effect responses.
|
|
5. The browser runtime validates the build fingerprint and applies effects within the current root.
|
|
|
|
```rust,ignore
|
|
#[hemx::handler]
|
|
async fn add_todo(form: NewTodo) -> impl IntoEffect {
|
|
ui::todos().append(TodoRow::from(form))
|
|
}
|
|
```
|
|
|
|
```html
|
|
<form data-hemx-form="new_todo">
|
|
<input name="title" required>
|
|
<button type="submit">Add</button>
|
|
</form>
|
|
<ul data-hemx-slot="todos"></ul>
|
|
```
|
|
|
|
## Design boundary
|
|
|
|
Hemx owns checked UI effects and their browser runtime. It does not own routing,
|
|
databases, authentication, CSS, or application state. Those remain ordinary
|
|
Rust and web concerns. Browser-specific behavior belongs in explicit leaf islands
|
|
rather than a second application model.
|
|
|
|
The normal application path is:
|
|
|
|
- `hemx` for handler and effect APIs;
|
|
- `hemx-build` for generated resources;
|
|
- `hemx-axum` for Axum integration;
|
|
- `hemx-js` for the browser effect runtime.
|
|
|
|
Server-side Wasm uses the same core crates and canonical effect batches; it does
|
|
not require a separate Hemx Wasm runtime package.
|
|
|
|
## Workspace
|
|
|
|
| Package | Purpose |
|
|
| --- | --- |
|
|
| `hemx` | Application-facing facade and handler macro export |
|
|
| `hemx-core` | Effect types, protocol values, validation, and runtime primitives |
|
|
| `hemx-derive` | Procedural macros |
|
|
| `hemx-build` | Build-time template analysis and generated resources |
|
|
| `hemx-axum` | Axum routes, responses, assets, and server push |
|
|
| `hemx-js` | Browser runtime source |
|
|
| `hemx-test` | Test support for applications |
|
|
|
|
## Agent skill
|
|
|
|
The optional [`idiomatic-hemx`](https://github.com/tmk241/hemx-skills) skill
|
|
helps coding agents apply Hemx's generated-resource and server-owned effect
|
|
model:
|
|
|
|
```console
|
|
npx skills@latest add tmk241/hemx-skills --skill idiomatic-hemx
|
|
```
|
|
|
|
## Development
|
|
|
|
```console
|
|
cargo fmt --all -- --check
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
cargo test --workspace --all-targets --all-features
|
|
cargo deny check licenses sources
|
|
```
|
|
|
|
## Related projects and acknowledgements
|
|
|
|
[htmx](https://htmx.org/) helped popularize the HTML-over-the-wire,
|
|
hypermedia-driven approach that inspired Hemx. Hemx is an independent
|
|
implementation and does not bundle htmx.
|
|
|
|
Hemx builds on [Hemplate](https://github.com/tmk241/hemplate),
|
|
[Tokio](https://github.com/tokio-rs/tokio),
|
|
[Axum](https://github.com/tokio-rs/axum), and the Rust procedural-macro
|
|
ecosystem. Thank you to their maintainers and contributors.
|
|
|
|
## License
|
|
|
|
MIT
|