Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vertz.dev/llms.txt

Use this file to discover all available pages before exploring further.

Vertz ships a native runtime (vtz) — a standalone Rust binary with an embedded V8 JavaScript engine. It starts in ~5ms and includes a dev server with SSR + HMR, a built-in test runner, and a package manager. No Node.js required.

​
How it works

vtz is the primary Vertz CLI. Run it directly — no extra configuration needed.

​
Command architecture

Not all vtz commands work the same way. Understanding the distinction helps avoid surprises:
CommandEngineWhat it does
vtz devV8 (built-in)Dev server with SSR, HMR, and TypeScript compilation
vtz testV8 (built-in)Test runner with Vitest-compatible API (details)
vtz run <script>Shell (spawns process)Executes a package.json script via sh -c
vtz exec <cmd> / vtzxShell (spawns process)Runs a binary from node_modules/.bin via sh -c
vtz install / add / removeRust (native)Package management with native dependency resolution
V8 commands (dev, test) run JavaScript inside the vtz binary’s own V8 engine. They use Vertz’s module loader, compiler, and runtime APIs (like @vertz/test and vertz:sqlite). Shell commands (run, exec) spawn a child process through your system shell. They add node_modules/.bin to the PATH, then hand off execution — similar to npm run or npx. The spawned process uses whatever runtime the script calls for (Node.js, Bun, etc.).
Use vtz test to run your tests — it’s the built-in test runner with watch mode, coverage, and a Vitest-compatible API. Running a third-party test runner via vtz run or vtz exec spawns it as a separate process and won’t use the Vertz test runtime.

​
Installation

Install the vtz binary directly — works on macOS and Linux, both x64 and ARM: 
curl -fsSL https://raw.githubusercontent.com/vertz-dev/vertz/main/install.sh | sh
This installs to ~/.vtz/bin/ and creates a vertz symlink. The script auto-detects your platform and architecture. To install a specific version: 
VTZ_VERSION=0.2.47 curl -fsSL https://raw.githubusercontent.com/vertz-dev/vertz/main/install.sh | sh

​
Via npm (existing projects)

If you already have a project with package.json, the vertz meta-package includes @vertz/runtime as an optional dependency. Running vtz install (or npm install) resolves the platform-specific binary automatically. To add the runtime explicitly: 
vtz add -d @vertz/runtime

​
From source

For contributors working on the Vertz monorepo: 
cd native
cargo build --release
# Binary is at native/target/release/vtz
The CLI automatically detects local monorepo builds — no extra config needed.

​
Binary resolution

The CLI resolves the runtime binary in this order:
  1. VERTZ_RUNTIME_BINARY env var — explicit path override (fail-fast if set but missing)
  2. Monorepo local build — native/target/release/vtz or native/target/debug/vtz
  3. npm package — @vertz/runtime resolves the platform-specific binary
  4. Error — if none found, prints installation instructions and exits

​
Supported platforms

PlatformArchitecturenpm package
macOSARM (M1/M2/M3/M4)@vertz/runtime-darwin-arm64
macOSIntel (x64)@vertz/runtime-darwin-x64
Linuxx64@vertz/runtime-linux-x64
LinuxARM64@vertz/runtime-linux-arm64

​
CLI commands

The vtz binary supports the following commands: 
vtz dev              # Start development server
vtz test             # Run tests
vtz install          # Install dependencies
vtz add <pkg>        # Add a package
vtz remove <pkg>     # Remove a package
vtz update [pkg]     # Update packages (or all if no pkg specified)
vtz run <script>     # Run a package.json script
vtz exec <cmd>       # Run a command from node_modules/.bin
vtzx <cmd>           # Shorthand for vtz exec (like npx)
vtz self-update      # Update the vtz binary itself

​
Dev server options

vtz dev --port 3000       # Set port (default: 3000)
vtz dev --host 0.0.0.0   # Set host (default: localhost)
vtz dev --open            # Open browser on start
vtz dev --no-typecheck    # Skip TypeScript checking
vtz dev --inspect         # Enable Chrome DevTools debugging
vtz dev --inspect-brk     # Debug from the first statement
For full debugging setup (Chrome DevTools, VS Code, breakpoints), see Debugging with Chrome DevTools.

​
Updating

The fastest way to update the vtz binary: 
vtz self-update
This downloads the latest release from GitHub and replaces the current binary in place. To update to a specific version: 
vtz self-update --version 0.3.0

​
Via npm

If you installed the runtime through npm, update the package instead: 
vtz update @vertz/runtime

​
Automatic update notifications

vtz checks for new versions automatically after running dev and install commands. When an update is available, you’ll see: 
  Update available: 0.2.46 → 0.2.47
  Run `vtz self-update` to update
The check is non-blocking (won’t slow down your workflow), cached for 24 hours, and silently skipped if the network is unavailable. To disable update checks (e.g. in CI): 
VTZ_NO_UPDATE_CHECK=1 vtz dev

​
Verifying your installation

vtz --version
# vtz 0.2.47
If you see a version mismatch warning between the CLI and the runtime, update both: 
vtz self-update          # update the runtime binary
vtz update @vertz/cli    # update the CLI package