Skip to content
acheulPublic

About

Reactive State Management from Rust/Wasm side

Resources

Contributing

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

Ahoi: Reactivity from Rust to JS

Render components with JS, manage state with Rust. The best of both.

github.com crates.io npm docs.rs Book

Ahoi is a fine-grained reactive state engine written in Rust. Rust owns the data and reactivity; a JS framework owns rendering. The two talk over a thin, type-safe wasm bridge.

Adapters ship for Solid, React, Vue, and Svelte. The core is framework-agnostic, so plain JS works too.

Read the Book to get started!


Core idea

"Rust for Rust, Js for Js"

  • Rust holds the truth: all state, derivations, and effects live in Rust.
  • JS just renders: the frontend subscribes to values and pushes user input back.
  • Bridge is bidirectional: values flow Rust→JS (push) and JS→Rust (write).

Why Ahoi?

  • 💥 Js Framework + Wasm: maintain communication between JS reactive state & rust-side data all by hand.

  • 💥 Rust Framework: should handle everything in rust, including ones which JS fits better! (ex. event handling)

  • ✔️ Ahoi removes these pain points. Use rust for rust, JS for JS. Keep reactivity.


A taste

On the Rust side, state lives in a reactive Stock, and a key enum declares what JS can subscribe to; each #[ret(..)] is the type JS gets back:

#[derive(Stock, Serialize, Deserialize)]
pub struct State {
    count: i32,
}

#[derive(Rets, Serialize, Deserialize)]
pub enum Hail {
    #[ret(i32)]
    Count,
    #[ret(i32)]
    Doubled,
}

fn run_hail(key: Hail) -> JsValue {
    let state = use_context::<Stock<State>>().unwrap();
    match key {
        // read-write: JS can write back into the stock
        Hail::Count => state.count().set_hail::<Converter>(),
        // read-only, recomputed only when `count` actually changes
        Hail::Doubled => state.count().memo(|c| *c * 2).set_read_hail::<Converter>(),
    }
}

On the JS side, those keys resolve to fully-typed signals of the host framework (SolidJS here):

function Counter() {
  const pier = usePier();
  const [count, setCount] = pier.hail("Count"); // () => number
  const doubled = pier.readHail("Doubled"); // () => number

  return (
    <>
      <p>
        {count()} · {doubled()}
      </p>
      <button onClick={() => setCount(count() + 1)}>+1</button>
    </>
  );
}

Keys are plain values ("Count", { Item: 3 }, no constructors), and their return types resolve from the generated Rets maps, so count() is number. Ahoi is not a Rust→TypeScript converter: bring your own (ts-rs, Tsify, Tsain, …); Ahoi only adds what no general-purpose converter knows: what each key returns.

For the full setup (Cargo/npm install, the bridge wiring, type export, and one-shot Tell commands), follow the Quick Start in the Book.


Framework adapters

Every adapter is a subpath of the same package; the framework is an optional peer dependency, so you only install what you use.

Import Provides
@acheul/ahoi-js/solid PierProvider, usePier() → .hail / .readHail / .tell
@acheul/ahoi-js/react PierProvider, useHail, useReadHail, useTell
@acheul/ahoi-js/vue PierProvider, useHail (writable ref), useReadHail, useTell
@acheul/ahoi-js/svelte providePier, useHail (store), useReadHail, useTell
@acheul/ahoi-js AhoiStorage, the framework-agnostic core for anything else

Using Preact? Use @acheul/ahoi-js/react and alias react/react-dom to preact/compat, as with any React library.


Learn more

The Book covers everything in depth:

  • Reactivity: Stock, Memo, Effect, async Action/Resource, stock derivation, and Sphere (the unit of reactive lifetime).
  • The JS bridge: Pier, Hail & Tell, converters, and exporting types.
  • Framework guides: per- framework usage with live demos.

Playground Examples

Four playgrounds share one wasm crate, each exercising the same bridge features (writable hails, memos, path-derived writes, async Resource/Action, enum and map values on the wire, nested-pier cleanup), plus a benchmark app:

See playgrounds/playgrounds.md for how to run them.


Awesome Examples

  • Ahoi-Palette: Rust handles a language model to turn words into a palette, and SolidJS renders it.

AI Usage Disclaimer

See AI Usage Disclaimer of current version.


License

MIT LICENSE

About

Reactive State Management from Rust/Wasm side

Resources

Contributing

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages