Forge Documentation

Forge is a Rust framework that compiles backend functions (queries, mutations, jobs, crons, workflows, and webhooks) into a single runtime backed by PostgreSQL. It generates frontend bindings from the same Rust source of truth, with first-class support for SvelteKit and Dioxus today.

Quick start

curl -fsSL https://tryforge.dev/install.sh | sh  # or: cargo install forgex
forge new my-app --template with-svelte/minimal
cd my-app
docker compose up --build

Runs Docker Compose with PostgreSQL, backend (cargo-watch), and the selected frontend target. Use docker compose down -v to reset. Choose a with-dioxus/* template if you want a Dioxus frontend instead of SvelteKit.

Learn by building

New to Forge? Follow the tutorials in order:

1. Build a Real-Time Todo App -- queries, mutations, subscriptions, and type-safe frontend bindings with SvelteKit or Dioxus
2. Add Authentication -- JWT tokens, registration, login, refresh token rotation, and protected routes
3. Master Background Processing -- background jobs with retries, cron schedules, and durable multi-step workflows
4. Ship to Production -- build a single binary, configure for production, add observability, and scale

Each tutorial builds on the previous one and uses real code from the Forge example projects.

Documentation map

• Start: Quick first app, project structure
• Tutorials: Step-by-step guides that teach core features
• Build: Deep reference for queries, mutations, jobs, workflows, scheduled tasks, webhooks, and reactivity
• Connect: Generated TypeScript/Rust client, progress tracking
• Ship: Configuration, deployment, and testing
• Scale: Multiple nodes, worker pools, and global deployments
• Reference: CLI, context methods, macro attributes, and error codes

Core concepts

#[forge::query]
pub async fn list_todos(ctx: &QueryContext) -> Result<Vec<Todo>> {
    sqlx::query_as!(Todo, "SELECT * FROM todos")
        .fetch_all(ctx.db())
        .await
        .map_err(Into::into)
}

// Auto-generated, type-safe
import { listTodos$ } from '$lib/forge';

const todos = listTodos$();

Queries and mutations are exposed as RPC endpoints under /_api/rpc and used by the generated frontend bindings. SvelteKit projects get TypeScript clients and stores; Dioxus projects get Rust bindings and hooks. Subscriptions use PostgreSQL LISTEN/NOTIFY plus a SSE connection to push updates.

Background jobs

#[forge::job(
    priority = "high",
    retry(max_attempts = 5, backoff = "exponential")
)]
pub async fn send_email(ctx: &JobContext, args: EmailArgs) -> Result<()> {
    ctx.progress(0, "Sending...")?;
    // ...
    ctx.progress(100, "Sent")?;
    Ok(())
}

Jobs are stored in PostgreSQL and claimed with FOR UPDATE SKIP LOCKED. Retry policy, priority, and progress updates are stored alongside the job record.

Webhooks

#[forge::webhook(
    path = "/hooks/stripe",
    signature = WebhookSignature::hmac_sha256("Stripe-Signature", "STRIPE_WEBHOOK_SECRET"),
    idempotency = "header:Idempotency-Key",
)]
pub async fn stripe(ctx: &WebhookContext, payload: Value) -> Result<WebhookResult> {
    ctx.dispatch_job("process_payment", payload.clone()).await?;
    Ok(WebhookResult::Accepted)
}

Webhook handlers run inside the Forge runtime and can validate signatures, enforce idempotency, and enqueue background work.

Workflows

#[forge::workflow]
pub async fn onboarding(ctx: &WorkflowContext, user_id: Uuid) -> Result<()> {
    ctx.step("welcome_email", || async {
        send_welcome(user_id).await
    })
    .run()
    .await?;

    ctx.sleep(Duration::from_secs(3 * 24 * 60 * 60)).await?;

    ctx.step("check_activation", || async {
        check_user_active(user_id).await
    })
    .compensate(|_| async move { send_reminder(user_id).await })
    .run()
    .await?;

    Ok(())
}

Workflow state is persisted in PostgreSQL so steps resume after restarts. Durable timers and compensation handlers are recorded per step.

PostgreSQL integration

Forge relies on core PostgreSQL features for coordination and data propagation:

• FOR UPDATE SKIP LOCKED for job queues
• LISTEN/NOTIFY for real-time subscriptions
• Advisory locks for leader election and migration coordination
• WAL durability for workflow and job state
• sqlx macros plus .sqlx/ offline cache for compile-time query validation

Build output

cargo build --release
./target/release/my-app

The release binary embeds the Forge runtime and can optionally bundle the frontend build using the embedded-frontend feature.

Requirements

Forge requires PostgreSQL 15+ and is released under the MIT License.

Next: First App or jump to Tutorials