Search
Contribute

Edit this documentation

Translate the documentation or open the complete project on your computer.

Nothing is published until you choose to submit your work.

Development Setup

Set up your development environment for Wails v3 development

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 only for frontend integration examples.

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)
  1. Configure workspace settings (.vscode/settings.json):
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 ./...
cd ..

Specific Package Tests

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

Run with Coverage

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

Run with Race Detector

bash
cd v3
go test ./... -race

Working with Documentation

The Wails v3 documentation is written in M-Press. English source files live in
docs/mpress/content/; translations live in language directories such as
fr/ and id/.

Preview and validate documentation changes from the repository root:

bash
go install github.com/leaanthony/mpress/cmd/mpress@v1.0.17
mpress dev
mpress build --strict --no-purge-css
mpress check
# Use `python` on Windows if `python3` is unavailable.
python3 docs/mpress/scripts/check_site.py docs/mpress/site

The production site is static. Node.js, a translation provider, and Cloudflare
credentials are not required for local documentation work.

Debugging

Debugging Go Code

VS Code:

Create .vscode/launch.json:

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: