# Hyperide
A contraction of [**hyper**media](https://hypermedia.systems/)
[oxyhydrox**ide**](<https://en.wikipedia.org/wiki/Iron(III)_oxide-hydroxide>).
This library provides utilities to help develop within the hyperide stack.
## The Hyperide Stack Contains
- A backend provider, your choice of axum (server) or vercel (serverless)
- A database provider, your choice of planetscale (mysql) or turso (sqlite)
- HTML in Rust (through the `hyperide!` macro)
- Style in HTML (tailwind)
- Hypermedia requests in HTML (htmx)
- Scripted interactivity in HTML (hyperscript)
Through combining these technologies, you can develop fullstack hypermedia
applications entirely from within Rust.
## Backend
The stack recommends using [Axum](https://github.com/tokio-rs/axum) optionally
and [Vercel](https://github.com/vercel-community/rust) for your backend.
### Axum
You can learn how to use Axum by looking at it's documentation. Use `hyperide!`
to build your HTML responses.
```rust
async fn greet(Path((name,)): Path<(String,)>) -> Html<String> {
Html(hyperide! {
<p>{"Hello, "}<strong>{name}</strong>{"!"}</p>
})
}
```
### Vercel
To use vercel, you will need to create and modify the following files:
`/vercel.json`
```json
{
"rewrites": [{ "source": "/:path(.*)", "destination": "/api/main" }],
"functions": {
"api/main.rs": {
"runtime": "vercel-rust@4.0.2"
}
}
}
```
`/.vercelignore`
```
target/
```
`/Cargo.toml`
```toml
# add this section
[[bin]]
name = "main"
path = "api/main.rs"
```
`/api/main.rs`
```rust
use axum::{extract::Path, routing::get, Router};
use vercel_runtime::Error;
#[tokio::main]
async fn main() -> Result<(), Error> {
let app = todo!("Put your axum router here");
hyperide::vercel::run(app).await
}
```
## Database
The stack recommends choosing between [Planetscale](https://planetscale.com/)
and [Turso](https://turso.tech/) for your database backend, as both can run in
serverless environments. Alternatively, use
[SQLx](https://github.com/launchbadge/sqlx) and your favourite database.
## HTML In Rust
Macros for generating HTML inside Rust. Think of it a bit like leptos, yew, or
any other crate that provides HTML in Rust, but without 99% of the
functionality. You write HTML like syntax, and you get a `String` back.
```rust
hyperide! {
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
</head>
<body>
<h1>{"Hello, world!"}</h1>
<{returns_tag()}>This is in a closed paragraph.</_>
{my_component("Foo", "bar")}
</body>
</html>
}
```
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
</head>
<body>
<h1>Hello, world!</h1>
<p>This is in a closed paragraph.</p>
<p><strong>Foo: </strong>bar</p>
</body>
</html>
```
## Style In HTML
It is recommended that you set up [tailwind](https://tailwindcss.com/) as part
of your build step. You will need the tailwind cli installed. The script will
attempt to use `tailwind` as the binary by default, but you can overwrite this
with the `TAILWIND_BIN` environment variable.
`/tailwind.config.js`
```js
module.exports = {
content: ["./src/**/*.rs", "./api/**/*.rs"],
plugins: [],
};
```
`/tailwind.in.css`
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```
`/build.rs`
```rs
use std::path::Path;
fn main() {
hyperide::tailwind::bootstrap(
Path::new("./tailwind.config.js"),
Path::new("./tailwind.in.css"),
);
}
```
Use the `include_tailwind!` macro in the `<head>` of your responses to include
the stylesheet generated by tailwind.
## Hypermedia Requests In HTML
I recommend you read the [Hypermedia Systems book](https://hypermedia.systems/)
and [htmx](https://htmx.org/) documentation. Use `hyperide::htmx::include_htmx!`
to add it into the `<head>` of your responses.
## Scripted interactivity in HTML (hyperscript)
To add simple inline scripting support using
[hyperscript](https://hyperscript.org/). Use
`hyperide::hyperscript::include_hyperscript!` to add it into the `<head>` of
your responses.
## VSCode Syntax Highlighting
This is what you want:
https://marketplace.visualstudio.com/items?itemName=brvnonascimento.code-html-macro-server