Oxirast

The fine-grained, lightning-fast WebAssembly framework for Rust.

Why Oxirast?

Most frontend frameworks rely on a Virtual DOM — when state changes, they re-render your entire component, diff a new VDOM tree against the old one, and patch the real DOM. This diffing step is expensive and grows with your component tree.

Oxirast takes a fundamentally different approach: Fine-Grained Reactivity.

State lives in Signals. When a Signal mutates, Oxirast does not re-render the component. It reaches directly into the live browser DOM and surgically updates only the specific text node or attribute that depends on that Signal. The rest of your tree is never touched.

Features

• 🎯 True Fine-Grained Reactivity — Signals mutate, DOM updates. No re-renders. No diffing.
• 🦀 100% Rust — Write your entire frontend in one language with full type safety.
• 📝 Declarative UI via rsx! — HTML-like syntax compiled to optimised Wasm at build time.
• 🔀 Built-in SPA Router — History-based client-side routing with automatic memory cleanup.
• ⚡ Zero-Config CLI — Scaffold, compile, and hot-reload with a single command.
• 🧹 Automatic Memory Management — Wasm-to-JS garbage collector purges orphaned closures and Signals on page transitions, preventing memory leaks.

Workspace Structure

This repository is a Cargo workspace containing three crates:

oxirast/
├── oxirast-core/      # Runtime engine — Signals, VNode, Router, DOM bindings
├── oxirast-parser/    # Compile-time procedural macro engine — rsx! transformation
└── oxirast-cli/       # Developer CLI — scaffold, serve with hot-reload

oxirast-core

The runtime engine. Contains the Virtual DOM, the Signal<T> reactivity system, the Router, async fetch hooks (use_fetch), the Context API (provide_context / use_context), and all wasm-bindgen DOM bindings.

oxirast-parser

The compile-time macro engine. Transforms your rsx! HTML-like syntax into optimised Rust/VNode instructions. Handles bind_text directive wiring and on_* event listener compilation.

oxirast-cli

The developer toolkit. A globally installed binary that scaffolds new projects and runs a hot-reloading development server at http://localhost:3000.

Quick Start

1. Install the CLI

cargo install oxirast-cli

2. Scaffold a new project

oxirast-cli init my_app
cd my_app

3. Start the dev server

oxirast-cli

Your app is now compiling to WebAssembly and running at http://localhost:3000 with hot-reloading enabled.

Usage

Components & the rsx! Macro

use oxirast_core::VNode;
use oxirast_parser::rsx;

#[allow(non_snake_case)]
pub fn WelcomeCard() -> VNode {
    rsx!(
        <div class="card">
            <h1>"Welcome to Oxirast"</h1>
            <p>"Compiled to WebAssembly."</p>
        </div>
    )
}

Reactivity with Signals

use oxirast_core::{use_state, VNode};
use oxirast_parser::rsx;

#[allow(non_snake_case)]
pub fn Counter() -> VNode {
    let count        = use_state(0);
    let display_text = use_state(String::from("Clicks: 0"));

    let btn_count = count.clone();
    let btn_text  = display_text.clone();

    let handle_click = move |_e| {
        let next = btn_count.get() + 1;
        btn_count.set(next);
        btn_text.set(format!("Clicks: {}", next));
    };

    rsx!(
        <div class="counter-box">
            <h2 bind_text={display_text}></h2>
            <button on_click={handle_click}>"Increment"</button>
        </div>
    )
}

Single Page Routing

use oxirast_core::{Router, Signal, VNode};
use oxirast_parser::rsx;

#[allow(non_snake_case)]
pub fn Home(nav: Signal<String>) -> VNode {
    let nav_clone = nav.clone();
    let go_about = move |_| nav_clone.set(String::from("/about"));

    rsx!(
        <div>
            <h1>"Home Page"</h1>
            <button on_click={go_about}>"Go to About"</button>
        </div>
    )
}

#[wasm_bindgen::prelude::wasm_bindgen(start)]
pub fn main() {
    Router::new("root")
        .route("/",      Home)
        .route("/about", About)
        .start();
}

Cargo.toml Dependencies

Add the following to your project's Cargo.toml:

[dependencies]
oxirast-core   = "0.1.1"
oxirast-parser = "0.1.1"
wasm-bindgen   = "0.2"

[lib]
crate-type = ["cdylib"]

Project Structure (Scaffolded App)

my_app/
├── Cargo.toml
├── Cargo.lock
├── public/
│   ├── index.html     # HTML shell — Oxirast mounts into <div id="root">
│   └── style.css      # Global styles
└── src/
    ├── lib.rs         # Entry point & Router configuration
    └── pages/
        ├── home.rs
        └── about.rs

Roadmap

• Signal<T> fine-grained reactivity
• rsx! macro — HTML-like declarative UI
• bind_text directive
• on_* event listener attributes
• Client-side SPA Router with History API
• use_state / use_fetch hooks
• Context API (provide_context / use_context)
• Automatic Wasm-to-JS GC (memory reaper)
• Zero-config CLI (init + serve)
• oxirast-cli build — optimised release builds with wasm-opt
• oxirast-cli clean
• --template flag for init
• oxirast.toml project configuration
• Server-Side Rendering (SSR)
• Component hot-module replacement (HMR)
• bind_attr directive for reactive HTML attributes

Contributing

Contributions are welcome. Please open an issue first to discuss any significant changes.

1. Fork the repository
2. Create a feature branch — git checkout -b feat/your-feature
3. Commit your changes — git commit -m "feat: add your feature"
4. Push to the branch — git push origin feat/your-feature
5. Open a Pull Request

License

MIT License © Michael (kinuthia)

See LICENSE for the full text.