#Quickstart: Build Your First Ranvier Service

Version: 0.51.0 Updated: 2026-07-16 Applies to: ranvier facade Category: Getting Started

This is the canonical first-user path. It uses the public ranvier facade so your application does not need to assemble Ranvier's internal crates.

#Prerequisites

Rust 1.93.0 or newer
Cargo

rustc --version

#1. Install through the facade

Use this path for a new application:

cargo new ranvier-quickstart
cd ranvier-quickstart
cargo add [email protected]
cargo add tokio@1 --features macros,rt-multi-thread

Do not start by adding ranvier-core, ranvier-runtime, or ranvier-http separately. Those crates remain available for advanced integration, but the facade is the maintained onboarding contract.

#2. Add one typed transition and native HTTP ingress

Replace src/main.rs with:

use ranvier::prelude::*;

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let hello = Axon::<(), (), String>::new("hello").then(greet);

    Ranvier::http()
        .bind("127.0.0.1:3000")
        .route("/", hello)
        .run(())
        .await?;

    Ok(())
}

Run the service:

cargo run

In another terminal, request http://127.0.0.1:3000/:

curl http://127.0.0.1:3000/

The code above is compiled as the repository's facade-only quickstart contract. It exercises the Stable Candidate Transition, Outcome, Bus, Axon, and native Ranvier::http() path.

#3. Continue with three maintained workflows

The next learning surface is deliberately bounded to three workflows:

Workflow	What it proves	Support contract
Typed state progression	compile-time handoff between Axon steps	Canonical / Developer gate
Typed JSON native HTTP	typed request/response boundary through Ranvier ingress	Supported / Release gate
Bus capability policy	explicit resource presence and access policy	Supported / Release gate

From a Ranvier source checkout, compile the exact workflow set with:

cargo check -p typed-state-tree -p typed-json-api -p bus-capability-demo --locked

These packages are part of the recurring candidate compile contract. They do not require external runtime services.

#4. Choose native or hybrid at the HTTP boundary

Starting point	Choose	Why
New service whose endpoints are decision workflows	Native `Ranvier::http()`	One visible ingress/guard/Outcome model and Schematic-aware routing
Existing Axum service with selected complex endpoints	Axum + Ranvier hybrid	Keep Axum routing and Tower middleware; invoke Axon only for decision logic

Native is the default onboarding path. Hybrid is a deliberate integration choice, not a second installation recipe. Tower/Axum middleware remains outside Ranvier's Schematic unless the application bridges that state into the Bus explicitly.

#5. Support boundary

Stable Candidate APIs are governed by the API stability contract.
Canonical examples run in the Developer gate; Supported examples run in the Release gate.
Schema-described Branch, Jump, and Emit payloads and runtime Bus presence checks are not compile-time type guarantees.
macOS and the recurring platform/MSRV matrix are not claimed verified until M419 publishes that evidence.

#6. Experimental and Lab paths come last

After the quickstart and the three maintained workflows compile, use the Examples Explorer to find Lab or experimental integrations. Those examples are useful references but are not part of the routine Developer or Release support promise.