Installation
Complete installation guide for Spanwright and all required dependencies.
Prerequisites
Spanwright requires several external tools to function properly. Follow this guide to install everything you need.
System Requirements
- Operating System: macOS, Linux, or Windows (with WSL2)
- Node.js: 22.0.0 or higher
- pnpm: 9.0.0 or higher
- Docker: For running Cloud Spanner emulator
- Go: 1.24.5 or higher (for database tools)
- Git: For version control
Node.js Installation
Using Node Version Manager (Recommended)
For macOS/Linux:
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Restart terminal, then install Node.js
nvm install 22
nvm use 22
For Windows:
# Install nvm-windows from: https://github.com/coreybutler/nvm-windows
# Then run:
nvm install 22.0.0
nvm use 22.0.0
Direct Installation
Download from nodejs.org and install Node.js 22.0.0 or higher.
Verify installation:
node --version # Should show v22.x.x or higher
npm --version # Should show 10.x.x or higher
pnpm Installation
After installing Node.js, install pnpm:
# Install pnpm globally
npm install -g pnpm
# Verify installation
pnpm --version # Should show 9.x.x or higher
Docker Installation
Docker is required to run the Cloud Spanner emulator.
macOS
# Using Homebrew
brew install --cask docker
# Or download from https://docker.com/products/docker-desktop
Linux (Ubuntu/Debian)
# Install Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
Windows
Download Docker Desktop from docker.com
Verify installation:
docker --version
docker run hello-world
Go Installation
Using Package Manager
macOS:
brew install go
Linux:
# Download and install
wget https://go.dev/dl/go1.24.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.5.linux-amd64.tar.gz
# Add to PATH in ~/.bashrc or ~/.zshrc
export PATH=$PATH:/usr/local/go/bin
Windows: Download installer from go.dev
Verify installation:
go version # Should show go1.24.5 or higher
Required Go Tools
Install the additional Go tools that Spanwright projects use:
wrench (Cloud Spanner Schema Migration Tool)
go install github.com/cloudspannerecosystem/wrench@latest
spalidate (Database Validation Tool)
# Clone and install spalidate
git clone https://github.com/nu0ma/spalidate.git
cd spalidate
go install ./cmd/spalidate
Verify Go tools:
wrench --version
spalidate --version
Installing Spanwright
Global Installation (Recommended)
Install Spanwright globally to use it anywhere:
pnpm install -g spanwright
Verify installation:
spanwright --version
spanwright --help
Using npx (No Installation)
You can use Spanwright without installing it globally:
npx spanwright your-project-name
Version Management Tools (Optional)
For managing multiple versions of Node.js and Go:
mise (Recommended)
mise is a universal tool version manager:
# Install mise
curl https://mise.run | sh
# Add to shell profile
echo 'eval "$(mise activate bash)"' >> ~/.bashrc # for bash
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc # for zsh
# Install tools from project files
cd your-spanwright-project
mise install
asdf
Alternative version manager:
# Install asdf
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.13.1
# Add plugins
asdf plugin add nodejs
asdf plugin add golang
# Install from .tool-versions
asdf install
Platform-Specific Notes
macOS
Apple Silicon (M1/M2):
- Docker and Go have native ARM64 support
- All tools work natively without Rosetta
Intel Macs:
- Standard x86_64 installation
Linux
Ubuntu/Debian:
# Install additional dependencies
sudo apt update
sudo apt install -y curl wget git build-essential
RHEL/CentOS/Fedora:
# Install additional dependencies
sudo dnf install -y curl wget git gcc gcc-c++ make
Windows
WSL2 Setup (Recommended):
# Install WSL2 Ubuntu
wsl --install -d Ubuntu
# Inside WSL2, follow Linux installation steps
Native Windows:
- Install tools using Chocolatey or Scoop
- Docker Desktop required
- Git Bash recommended for terminal
Verification
After installing all prerequisites, verify your setup:
# Check versions
node --version # >= 22.0.0
pnpm --version # >= 9.0.0
docker --version # Any recent version
go version # >= 1.24.5
wrench --version # Latest
spalidate --version # Latest
# Test Docker
docker run hello-world
# Test Spanwright
spanwright --help
Troubleshooting
Common Issues
Docker permission denied:
# Linux: Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
Go tools not found:
# Ensure GOPATH/bin is in PATH
export PATH=$PATH:$(go env GOPATH)/bin
Node.js version issues:
# Use nvm to switch versions
nvm install 22
nvm use 22
Docker Spanner emulator issues:
# Pull latest emulator image
docker pull gcr.io/cloud-spanner-emulator/emulator:latest
Next Steps
Once everything is installed:
- Quick Start Guide - Create your first project in 5 minutes
- Project Structure - Understand generated project layout
- Configuration - Learn about project configuration options (Coming Soon)
Getting Help
- GitHub Issues: Report installation problems
- Documentation: Full documentation site
- Community: Join discussions