Tutorial

Build your first Ranvier circuit.

This walkthrough mirrors the latest hello-world example, exports schematic with CLI, and then uses the VSCode extension workflow.

1. Install Dependencies

cargo add ranvier
cargo add ranvier-macros
cargo add tokio --features full
cargo add anyhow

2. Define Transitions (latest hello-world)

use ranvier::prelude::*;
use ranvier_macros::transition;

#[derive(Clone)]
struct Greet;

#[transition]
async fn greet(_state: (), _resources: &(), _bus: &mut Bus) -> Outcome<String, anyhow::Error> {
    Outcome::Next("Hello, Ranvier!".to_string())
}

#[derive(Clone)]
struct Exclaim;

#[transition]
async fn exclaim(state: String, _resources: &(), _bus: &mut Bus) -> Outcome<String, anyhow::Error> {
    Outcome::Next(format!("{} 🚀", state))
}

3. Add schematic-mode guard + wire HTTP

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let hello = Axon::simple::<anyhow::Error>("HelloWorld")
        .then(greet)
        .then(exclaim);

    if hello.maybe_export_and_exit()? {
        return Ok(());
    }

    Ranvier::http()
        .bind("127.0.0.1:3000")
        .route("/", hello)
        .run(())
        .await
        .map_err(|e| anyhow::anyhow!("{}", e))?;

    Ok(())
}

Run the server with cargo run, then open http://127.0.0.1:3000.

4. Understand Resource Wiring

Shared resources (DB pools, tracers, config) are wired explicitly. You can pass a typed resource bundle to ingress or read from Bus when needed.

5. Explore Canonical Examples (Repository)

Hello World (HTTP)

cargo run -p hello-world

Typed State Tree

cargo run -p typed-state-tree

Schematic Baseline

cargo run -p basic-schematic

The canonical example index lives in the repository: ranvier/examples

6. Use Ranvier CLI for schematic/projection

cargo install ranvier-cli
ranvier schematic hello-world --output schematic.json

7. Use VSCode extension workflow

code --install-extension cellaxon.ranvier-vscode
# Command Palette:
# Ranvier: Open Circuit View
# Ranvier: Run Schematic Export

8. Generate Trace Projections

ranvier status projection-from-example order-processing-demo \
  --output ./dist/trace-order \
  --service "Ranvier Service" \
  --circuit-id order_processing \
  --circuit-version 0.1.0

After tutorial completion, move to /manual and select product manuals (`ranvier`, `cli`, `vscode`) for detailed operations.