VX Project Management Guide

Quick start: Run vx init to create vx.toml, vx setup to install all tools, vx dev to enter the dev environment. For existing projects, just run vx setup after cloning.

Project Setup

Initialize a Project

vx init                     # Create vx.toml interactively
vx init --template node     # Use a template
vx init --minimal           # Create minimal vx.toml

Project Detection

vx automatically detects project types and suggests tools:

vx analyze                  # Analyze project (detects languages, dependencies)
vx analyze --json           # JSON output for AI parsing

Detected ecosystems: Node.js, Python, Rust, Go, Java, .NET, C/C++, Zig Detected frameworks: React, Vue, Angular, Next.js, Nuxt, Svelte, Django, Flask, FastAPI, Tauri, Electron, React Native, NW.js, and more Detected package managers: npm, yarn, pnpm, bun, pip, uv, cargo, go modules

The project analyzer reads indicator files like package.json, pyproject.toml, Cargo.toml, go.mod, etc. to suggest the right tools.

vx.toml Configuration

Basic Structure

# vx.toml - Project tool configuration

[tools]
# Version constraints
node = "22"                 # Major version (any 22.x.x)
go = "1.22"                 # Minor version (any 1.22.x)
uv = "latest"               # Always use latest
rust = "1.80"               # Specific version
just = "*"                  # Any version

# Platform-specific tools
[tools.msvc]
version = "14.42"
os = ["windows"]            # Only install on Windows

[tools.brew]
version = "latest"
os = ["macos", "linux"]

[scripts]
# Development scripts
dev = "npm run dev"
test = "cargo test"
lint = "npm run lint && cargo clippy"
build = "just build"

# CI/CD scripts
ci = "just ci"
release = "just release"

[hooks]
# Lifecycle hooks
pre_commit = ["vx run lint"]
post_setup = ["npm install", "cargo fetch"]

Version Constraints

Platform-Specific Tools

[tools]
# Cross-platform tools
node = "22"
uv = "latest"

# Windows-only
[tools.msvc]
version = "14.42"
os = ["windows"]

# macOS/Linux only
[tools.brew]
version = "latest"
os = ["macos", "linux"]

Project Commands

Setup & Sync

vx setup                    # Full project setup (sync + hooks)
vx sync                     # Install all tools from vx.toml
vx sync --clean             # Remove unlisted tools
vx sync --check             # Check without installing

Running Scripts

vx run dev                  # Run development server
vx run test                 # Run tests
vx run build                # Build project
vx run --list               # List available scripts

Lock File

vx lock                     # Generate vx.lock
vx lock --update            # Update locked versions
vx lock --check             # Verify lock file

The vx.lock file ensures reproducible builds:

# vx.lock - Auto-generated, do not edit
[tools]
node = { version = "22.0.0", checksum = "sha256:..." }
go = { version = "1.22.0", checksum = "sha256:..." }

Environment Management

Project Environment

vx dev                      # Enter project environment
vx env list                 # List environments
vx env activate             # Print activation commands
eval $(vx env activate)     # Activate in shell

Environment Variables

Define in vx.toml:

[env]
NODE_ENV = "development"
DATABASE_URL = "postgresql://localhost:5432/dev"
API_KEY = { env = "API_KEY", required = true }

Dependency Management

Add/Remove Tools

vx add node@22              # Add tool to vx.toml
vx add go rust uv           # Add multiple tools
vx remove node              # Remove tool from vx.toml

Check Constraints

vx check                    # Verify tool constraints
vx check --json             # JSON output
vx check --fix              # Auto-fix issues

Multi-Package Projects

Monorepo Support

For monorepos, create vx.toml in root:

# Root vx.toml
[tools]
node = "22"
pnpm = "latest"

[scripts]
install = "pnpm install"
build = "pnpm -r build"
test = "pnpm -r test"

Workspace Packages

Individual packages can have their own vx.toml:

# packages/backend/vx.toml
[tools]
go = "1.22"

[scripts]
dev = "go run ./cmd/server"

Best Practices

1. Version Pinning

Pin versions for CI/CD:

[tools]
node = "22.0.0"             # Exact version for CI

2. Lock Files

Always commit vx.lock:

git add vx.lock

3. Scripts Organization

Group related scripts:

[scripts]
# Development
dev = "..."
watch = "..."

# Testing
test = "..."
test:watch = "..."

# Build
build = "..."
build:prod = "..."

4. Hooks for Quality

Use hooks for automated checks:

[hooks]
pre_commit = ["vx run lint", "vx run test"]
post_checkout = ["vx sync"]

Project Templates

Create reusable templates:

# Create template from current project
vx template create my-template

# Use template
vx init --template my-template

Template Structure

~/.vx/templates/my-template/
├── vx.toml
├── .gitignore
├── README.md
└── hooks/
    └── post_setup.sh