Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

Requirements

  • Rust 1.97.1 or newer (edition 2024). rust-toolchain.toml pins stable.
  • Node.js, for the frontend a generated project ships with.

That is all. A generated project uses SQLite by default, and the driver creates the file on first connect — there is no server to install, no container to start and no credentials to match. PostgreSQL 17 or MySQL 8 are needed only if you ask for one with arc new --db postgres.

Installing the arc CLI

Three routes to the same binary. The first is the one to use.

Download it. Take the archive for your platform from the releases page, unpack it, and put arc on your PATH. Linux, macOS and Windows, x86-64 and arm64, each with a .sha256. No toolchain, no compile, seconds.

Compile it.

cargo install arcature --features cli --locked

A release build of the whole framework, sea-orm and sqlx included; minutes.

--locked is not optional. Without it Cargo ignores the published lockfile and re-resolves, which currently selects a sea-schema that fails to build with can't find crate for async_trait.

With cargo binstall. It fetches the published binary rather than building one, and once it is on the machine every crate that declares binstall metadata — Arcature does — installs without a compile.

Getting binstall is itself a download, not a build. Its official script pulls the prebuilt binary into ~/.cargo/bin:

# Windows
Set-ExecutionPolicy Unrestricted -Scope Process; iex (iwr "https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.ps1").Content
# Linux and macOS
curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash

Then:

cargo binstall arcature

Do not reach for cargo install cargo-binstall. That builds it from source — several hundred crates, more than compiling Arcature would have cost — which is the opposite of the point.

Two things worth knowing before you run the script. It is curl | bash: you are executing code fetched at that moment, trusting GitHub and the cargo-bins organisation. And for Arcature alone it buys nothing over the download above, which is one signed archive and adds no tool to the machine. It pays off when you install Rust binaries regularly. If you would rather not pipe a script, binstall publishes signed archives on its own releases page and unpacking one into ~/.cargo/bin does the same job.

Check it:

$ arc version
arcature 0.1.3

Using Arcature as a library

To add the framework to a crate you already have, rather than generating one:

cargo add arcature

To follow main ahead of a release instead, depend on the repository and pin a revision — a branch reference will move under you.

[dependencies]
arcature = { git = "https://github.com/ArcatureLabs/Arcature", rev = "..." }

The smallest application

use arcature::application::EngineResult;
use arcature::prelude::*;

#[arcature::main]
async fn main() -> EngineResult<()> {
    Application::new()
        .routes(Routes::new([Route::get("/", index).name("home")]))
        .build()
        .run()
        .await
}

async fn index() -> Result<Response> {
    Ok(text(StatusCode::OK, "hello"))
}

Three things to notice.

.build() is required. Application::new() returns an ApplicationBuilder; .run() lives on Application. Forgetting .build() is a type error, not a runtime surprise.

run() returns EngineResult<()>, not the framework’s Result<()>, and EngineResult is not in the prelude — it lives at arcature::application::EngineResult. Engine failures (a port already bound, a database that will not connect) are a different kind of failure from a handler’s, and they deliberately do not share an error type.

Handlers return Result<Response>, where Result is Arcature’s. text, json, redirect and no_content build the common shapes.

The generated application

$ arc new blog --stack react --db postgres
Created blog at blog
  installing frontend dependencies (npm install)...

Next:
  cd blog
  arc key:generate     # writes APP_KEY into .env
  arc dev              # one port, backend and Vite together

A project is two halves, and only one of them is Rust. cargo resolves the crates on the first build; the frontend needs npm install run once, and arc new runs it. Pass --no-install to skip that and run arc install yourself later — arc dev refuses to start without it and says so, rather than letting Node fail on a missing vite.

arc new writes a Laravel-shaped project rather than a single file:

app/
  controllers/   models/     services/
  requests/      policies/   resources/
bootstrap/
  app.rs         state.rs
config/
database/migrations/
routes/mod.rs
resources/js/    resources/css/
public/
storage/
src/main.rs      src/lib.rs
tests/smoke.rs
.env

bootstrap/app.rs is the composition root. It loads .env, reads typed configuration, and wires the subsystems:

pub fn app() -> Result<Application<crate::bootstrap::AppState>> {
    dotenvy::dotenv().ok();
    let config = crate::config::load()?;
    Ok(Application::new()
        .routes(crate::routes::routes())
        .bind(&config.bind_addr)
        .port(config.port)
        .database(config.database)
        .cache(config.cache)
        .storage(config.storage)
        .mail(config.mail)
        .jobs(jobs_registry())
        .build())
}

bootstrap/state.rs defines AppState, the cloneable bundle every handler reaches through State<AppState>. Each field is an Option, because a subsystem that was never configured contributes None rather than a panic:

#[derive(Clone)]
pub struct AppState {
    pub db: Option<Db>,
    pub jobs: Option<Jobs>,
    pub cache: Option<Cache>,
    pub storage: Option<Storage>,
    pub mail: Option<Mailer>,
}

The state is produced after startup, from the started Resources, which is why it is a closure rather than a value:

pub fn state_fn() -> Arc<dyn Fn(&Resources, &Lifecycle) -> AppState + Send + Sync> {
    Arc::new(|res, _lc| AppState {
        db: res.db().cloned(),
        jobs: res.jobs().cloned(),
        cache: res.cache().cloned(),
        storage: res.storage().cloned(),
        mail: res.mail().cloned(),
    })
}

src/lib.rs puts the two together with run_with_state.

Features

Arcature’s features reduce the compile surface; they are not a self-assembly kit. default is a working full-stack application. Turn features off to compile less, not on to reach a usable state.

# The whole framework.
arcature = { git = "...", features = ["fullstack"] }

# An API server: no Inertia, no static assets pipeline.
arcature = { git = "...", default-features = false, features = ["api", "database", "auth", "validation"] }

The database driver is split three ways — db-postgres, db-sqlite, db-mysql — so a SQLite application does not compile the PostgreSQL protocol. The job queue requires PostgreSQL.

Next

Your first module to add a feature to the application you just generated, Routing for how requests reach handlers, or Inertia if you are building a page-driven frontend.