VoltroDocumentation

Installation

Prerequisites, supported Node versions, and the three ways to install the Voltro CLI.

Prerequisites

Tool Version Why
Node.js 24.x or newer --experimental-strip-types, native ESM, node:test.
pnpm 10.x or newer Workspace + lockfile semantics Voltro's scaffolder targets.
Postgres 16.x or newer Optional for dev; required in production for logical replication-backed subscriptions.

You don't need Docker for dev — Voltro ships an in-memory store. You'll want Docker (or a managed Postgres) when you turn on persistence.

Three ways to install

The CLI runs from the registry without a global install:

mkdir my-app && cd my-app
pnpx voltro create-project my-app

This is the smallest blast radius — pnpx fetches the latest CLI release into the local cache and discards it after.

An empty directory is enough: create-project writes the pnpm workspace root (pnpm-workspace.yaml, a root package.json with dev/build/test/typecheck, a .gitignore, git init) when it can't find one above you. Inside an existing workspace it adds nothing but the project. voltro init does the workspace-root half on its own, for when you want the repo prepared before you pick templates.

2. Per-project dependency

Once your project exists, the CLI is already a dependency of the api app's package.json, so:

pnpm --filter @my-app/api exec voltro dev

The api template's own dev script is voltro dev ., so pnpm dev in the app runs the CLI directly. At the workspace root, pnpm dev is pnpm -r --parallel dev — every app at once. You rarely call the filtered form directly.

3. Global install

pnpm add -g @voltro/cli
voltro version

Convenient for jumping between projects from any directory. Downside: the global binary can drift away from the version pinned in your project — pin it in ~/.npmrc or use a version manager if you go this route.

Verifying the install

voltro version
voltro list-templates

The second command prints the app templates the CLI can scaffold — dozens of them, across four kinds: api-* backends, frontend-* web apps, an edge-functions serverless bundle, and mobile-app (Expo). The output is generated from the templates the installed CLI actually ships, so it is the authority on what your version can scaffold; do not go by a list in a doc. For what each one demonstrates and when to pick it, see the app-template reference.

Editor setup

Voltro ships an AGENTS.md file at the root of every scaffolded project. AI coding agents (Claude Code, Cursor, GitHub Copilot Chat) automatically read it for project-specific guidance — file conventions, schema DSL, common patterns. You don't need to do anything to enable it.

For VSCode, the recommended extensions are:

  • dbaeumer.vscode-eslint
  • bradlc.vscode-tailwindcss
  • vivaxy.vscode-conventional-commits

Tailwind v4 needs no config — Voltro's Vite plugin auto-discovers the content from the module graph.

Test utilities

@voltro/testing is a separate, public package — it is not bundled into a scaffolded project. The moment you write your first test, add it (and vitest) as a devDependency of the app you're testing:

pnpm --filter @my-app/api add -D @voltro/testing vitest

voltro test then runs vitest against the current app. See the Testing section for the full surface — makeTestContext, the deterministic mocks, the workflow runner, and the dialect-parity harness.

Next