5 releases

0.0.6	Aug 1, 2023
0.0.5	Aug 1, 2023
0.0.4	Aug 1, 2023
0.0.3	Jul 19, 2023
0.0.2	Jul 18, 2023

#589 in Rust patterns

29 downloads per month

MIT license

170KB
477 lines

Hyperide

A contraction of hypermedia oxyhydroxide.

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 optionally and Vercel for your backend.

Axum

You can learn how to use Axum by looking at it's documentation. Use hyperide! to build your HTML responses.

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

{
  "rewrites": [{ "source": "/:path(.*)", "destination": "/api/main" }],
  "functions": {
    "api/main.rs": {
      "runtime": "vercel-rust@4.0.2"
    }
  }
}

/.vercelignore

target/

/Cargo.toml

# add this section
[[bin]]
name = "main"
path = "api/main.rs"

/api/main.rs

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 and Turso for your database backend, as both can run in serverless environments. Alternatively, use 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.

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.</_>
       <!-- "wildcard close tag ⬆️" -->
       {my_component("Foo", "bar")}
   </body>
   </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>
    <!-- "wildcard close tag ⬆️" -->
    <p><strong>Foo: </strong>bar</p>
  </body>
</html>

Style In HTML

It is recommended that you set up tailwind 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

module.exports = {
  content: ["./src/**/*.rs", "./api/**/*.rs"],
  plugins: [],
};

/tailwind.in.css

@tailwind base;
@tailwind components;
@tailwind utilities;

/build.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 and htmx 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. 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

Dependencies

~19–31MB
~557K SLoC