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:

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.

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. If your workspace ships a turbo dev pipeline, pnpm dev at the repo root delegates to it. 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. You'll see the api-backend* templates (api-backend, api-backend-mail, api-backend-mariadb, api-backend-storage) and the frontend-* templates (frontend-blank, frontend-docs, frontend-landing) — that's everything in place.

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