Development Setup

Development Environment Setup

This guide walks you through setting up a complete development environment for working on Wails v3.

Required Tools

Go Development

1. Install Go 1.25 or later:

   # Download from https://go.dev/dl/
   go version  # Verify installation

2. Configure Go environment:

   # Add to your shell profile (.bashrc, .zshrc, etc.)
   export GOPATH=$HOME/go
   export PATH=$PATH:$GOPATH/bin

3. Install useful Go tools:

   go install golang.org/x/tools/cmd/goimports@latest
   go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Node.js and npm

Required for building documentation and testing frontend integrations.

# Install Node.js 20+ and npm
node --version  # Should be 20+
npm --version

Platform-Specific Dependencies

macOS:

# Install Xcode Command Line Tools
xcode-select --install

# Verify installation
xcode-select -p  # Should output a path

Windows:

1. Install MSYS2 for a Unix-like environment
2. WebView2 Runtime (pre-installed on Windows 11, download for Windows 10)
3. Optional: Install Git for Windows

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.0-dev

Linux (Fedora/RHEL):

sudo dnf install gcc pkg-config gtk3-devel webkit2gtk3-devel

Linux (Arch):

sudo pacman -S base-devel gtk3 webkit2gtk

Repository Setup

Clone and Configure

# Clone your fork
git clone https://github.com/YOUR_USERNAME/wails.git
cd wails

# Add upstream remote
git remote add upstream https://github.com/wailsapp/wails.git

# Verify remotes
git remote -v

Build the Wails CLI

# Navigate to v3 directory
cd v3

# Build the CLI
go build -o ../wails3 ./cmd/wails3

# Test the build
cd ..
./wails3 version

Add to PATH (Optional)

Linux/macOS:

# Add to ~/.bashrc or ~/.zshrc
export PATH=$PATH:/path/to/wails

Windows:

Add the Wails directory to your PATH environment variable through System Properties.

IDE Setup

VS Code (Recommended)

1. Install VS Code: Download

2. Install extensions:

   • Go (by Go Team at Google)
   • ESLint
   • Prettier
   • MDX (for documentation)

3. Configure workspace settings (.vscode/settings.json):

   {
     "go.useLanguageServer": true,
     "go.lintTool": "golangci-lint",
     "go.lintOnSave": "workspace",
     "editor.formatOnSave": true,
     "go.formatTool": "goimports"
   }

GoLand

1. Install GoLand: Download

2. Configure:

   • Enable Go modules support
   • Set up file watchers for goimports
   • Configure code style to match project conventions

Verify Your Setup

Run these commands to verify everything is working:

# Go version check
go version

# Build Wails
cd v3
go build ./cmd/wails3

# Run tests
go test ./pkg/...

# Create a test app
cd ..
./wails3 init -n mytest -t vanilla
cd mytest
../wails3 dev

If the test app builds and runs, your environment is ready!

Running Tests

Unit Tests

cd v3
go test ./...

Specific Package Tests

go test ./pkg/application
go test ./pkg/events -v  # Verbose output

Run with Coverage

go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out

Run with Race Detector

go test ./... -race

Working with Documentation

The Wails documentation is built with Astro and Starlight.

cd docs

# Install dependencies
npm install

# Start dev server
npm run dev

# Build for production
npm run build

Documentation will be available at http://localhost:4321/

Debugging

Debugging Go Code

VS Code:

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Wails CLI",
      "type": "go",
      "request": "launch",
      "mode": "debug",
      "program": "${workspaceFolder}/v3/cmd/wails3",
      "args": ["dev"]
    }
  ]
}

Command Line:

# Use Delve debugger
go install github.com/go-delve/delve/cmd/dlv@latest
dlv debug ./cmd/wails3 -- dev

Debugging Platform Code

Platform-specific debugging requires platform tools:

• macOS: Xcode Instruments
• Windows: Visual Studio Debugger
• Linux: GDB

Common Issues

”command not found: wails3”

Add the Wails directory to your PATH or use ./wails3 from the project root.

”webkit2gtk not found” (Linux)

Install WebKit2GTK development packages:

sudo apt install libwebkit2gtk-4.0-dev  # Debian/Ubuntu

Build fails with Go module errors

cd v3
go mod tidy
go mod download

”CGO_ENABLED” errors on Windows

Ensure you have a C compiler (MinGW-w64 via MSYS2) in your PATH.

Next Steps

• Review Coding Standards
• Explore the Technical Documentation
• Find an issue to work on: Good First Issues