VoltroDocumentation

Getting started

Scaffold a Voltro project and boot it locally in under a minute.

Voltro is an AI-first, multi-tenant, reactive full-stack framework. You write your backend through file conventions for queries, mutations, actions, streams, workflows, and agents; hooks for reactive data; automatic live updates to every connected client over a single WebSocket.

This guide gets you from zero to a running stack in under a minute.

Prerequisites

  • Node.js 24+ — Voltro relies on the --experimental-strip-types flag and modern ESM behaviour.
  • pnpm 10+ — workspaces, fast installs, deterministic lockfiles.
  • Postgres 16+ (optional) — Voltro's dev mode runs against an in-memory store by default; switch to Postgres when you want logical replication-backed subscriptions, durable workflows, or to mirror production locally.

Scaffold a project

create-project runs inside an existing pnpm workspace — it walks up from your current directory looking for pnpm-workspace.yaml and writes the project into that workspace's apps/ directory. Run it from the root of your workspace:

pnpx voltro create-project acme \
  --api api-backend \
  --web frontend-landing \
  --port-range 5190-5199

This creates apps/acme/ inside the workspace with an api/ (Voltro backend) and a web/ (landing page) app. The project name is kebab-cased (so Acme becomes acme). The --port-range is recorded in project.json so every new app added later gets a unique port without you thinking about it.

Boot it

Install and run from the workspace root — there is no top-level acme/ directory to cd into; the project lives under apps/acme/:

pnpm install
pnpm dev

The dev orchestrator boots every app in parallel with HMR. By default:

  • api listens on :4000 (RPC over WebSocket on /ws)
  • web listens on the first port in your range (e.g. 5190)
  • The framework dashboard auto-launches on :5179 (set VOLTRO_DASHBOARD=off to skip it)

Open the web app's URL in a browser — anything you edit in apps/acme/api/ or apps/acme/web/src/ hot-reloads.

What you just got

  • File-based queries (*.query.ts) and mutations (*.mutation.ts) — no manual registration
  • Streams (*.stream.ts) for one-shot server-to-client element feeds
  • Reactive subscriptions wired to Postgres logical replication (or in-memory CDC for the dev store)
  • Multi-tenancy as a runtime primitive — drop the tenant() mixin on a table and the runtime scopes reads + flags cross-tenant writes
  • Durable workflows via @effect/workflow — long-running jobs survive deploys and crashes
  • AI primitives wrapping the Vercel AI SDK, plus a tool-calling convention
  • End-to-end type safety from your Postgres schema to your React components, no codegen step

Next steps

  • Why Voltro? — the bigger picture + what we won't build
  • Concepts — the vocabulary behind the framework
  • File conventions — what *.query.ts, *.mutation.ts, etc. actually do
  • Data overview — queries, mutations, actions, streams in five minutes