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:
bash
# Download from https://go.dev/dl/
go version  # Verify installation
  1. Configure Go environment:
bash
# Add to your shell profile (.bashrc, .zshrc, etc.)
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
  1. Install useful Go tools:
bash
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.

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

Platform-Specific Dependencies

macOS:

bash
# 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):

bash
sudo apt update
# Default GTK4 + WebKitGTK 6.0 stack (Ubuntu 24.04+ / Debian 13+)
sudo apt install build-essential pkg-config libgtk-4-dev libwebkitgtk-6.0-dev
# For the legacy -tags gtk3 path:
sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev

Linux (Fedora/RHEL):

bash
# Default GTK4 stack
sudo dnf install gcc pkg-config gtk4-devel webkitgtk6.0-devel
# Legacy GTK3 path:
sudo dnf install gtk3-devel webkit2gtk4.1-devel

Linux (Arch):

bash
# Default GTK4 stack
sudo pacman -S base-devel gtk4 webkitgtk-6.0
# Legacy GTK3 path:
sudo pacman -S gtk3 webkit2gtk-4.1

Repository Setup

Clone and Configure

bash
# 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

bash
# 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:

bash
# 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

  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:

bash
# 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

bash
cd v3
go test ./...

Specific Package Tests

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

Run with Coverage

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

Run with Race Detector

bash
go test ./... -race

Working with Documentation

The Wails documentation is built with Astro and Starlight.

bash
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:

bash
# 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.

“webkitgtk-6.0 not found” or “webkit2gtk not found” (Linux)

Install the development packages for whichever stack you’re building against:

bash
# Default GTK4 stack (Debian/Ubuntu):
sudo apt install libwebkitgtk-6.0-dev

# Legacy GTK3 path:
sudo apt install libwebkit2gtk-4.1-dev

Build fails with Go module errors

bash
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

Edit page

Last updated: