Skip to main content

Wails - Build desktop apps using Go & React

Shen Zhen, China

The traditional method of providing web interfaces to Go programs is via a built-in web server. Wails offers a different approach: it provides the ability to wrap both Go code and a web frontend into a single binary. The Wails cli makes this easy for you, by handling project creation, compilation and bundling.

Install Version 1.16.9


sudo pacman -S gcc pkgconf webkit2gtk gtk3

Install Wails

go install

But I found that you can also find it on PACMAN: community/wails 1.16.9-2:

sudo pacman -S wails

wails version
 _       __      _ __    
| |     / /___ _(_) /____
| | /| / / __ `/ / / ___/
| |/ |/ / /_/ / / (__  )  v1.16.9
The lightweight framework for web-like apps

Available commands:

   setup     Setup the Wails environment [default]
   migrate   Migrate projects to latest Wails release 
   init      Initialises a new Wails project 
   build     Builds your Wails project 
   serve     Run your Wails project in bridge mode 
   update    Update to newer [pre]releases or specific versions 
   issue     Generates an issue in Github

To finish the installation setup your Wails system by running the setup command wails setup and filling your handle and email.

Hello World

Generate a new project using the init command - leads to an error message

wails init wails-world
Wails v1.16.9 - Initialising project

2022/06/18 21:27:48 Could not load linuxdb.yaml

Install Version 2 Beta

go install

The application is installed in:


Running wails doctor will check if you have the correct dependencies installed. Change into the installation directory and run:

go run ./main.go doctor
Wails CLI v2.0.0-beta.42

Scanning system - Please wait (this may take a long time)...Done.

OS:             Manjaro Linux
Version:        Unknown
ID:             manjaro
Go Version:     go1.19
Platform:       linux
Architecture:   amd64

Version:                v2.0.0-beta.42
Package Manager:        pacman

Dependency      Package Name    Status          Version
----------      ------------    ------          -------
*docker         docker          Installed       1:20.10.17-1
gcc             gcc             Installed       12.1.0-3
libgtk-3        gtk3            Installed       1:3.24.34-1
libwebkit       webkit2gtk      Installed       2.36.4-2
npm             npm             Installed       8.15.1-1
pkg-config      pkgconf         Installed       1.8.0-1

* - Optional Dependency

Your system is ready for Wails development!

Build the Binary

Inside the install directory run:

sudo go mod tidy
sudo go build

You will end up with a wails bin file in go/pkg/mod/ Copy this file to your user bin directory and make sure that it is picked up:

sudo mv wails /usr/bin/wails
wails version

Scaffold your first Wails App

List all application templates:

wails init -l
Wails CLI v2.0.0-beta.42

TEMPLATE                        SHORT NAME      DESCRIPTION                              
Lit + Vite                      lit             Lit + Vite development server           
Lit + Vite (Typescript)         lit-ts          Lit + TS + Vite development server      
Plain HTML/JS/CSS               plain           A simple template using only HTML/CSS/JS
Preact + Vite                   preact          Preact + Vite development server        
Preact + Vite (Typescript)      preact-ts       Preact + Vite development server        
React + Vite                    react           React + Vite development server         
React + Vite (Typescript)       react-ts        React + Vite development server         
Svelte + Vite                   svelte          Svelte + Vite development server        
Svelte + Vite (Typescript)      svelte-ts       Svelte + TS + Vite development server   
Vanilla + Vite                  vanilla         Vanilla + Vite development server       
Vanilla + Vite (Typescript)     vanilla-ts      Vanilla + Vite development server       
Vue + Vite                      vue             Vue + Vite development server           
Vue + Vite (Typescript)         vue-ts          Vue + Vite development server

By default the init command will use the vanilla template. The following command will scaffold the React.js template:

mkdir wails-world
wails init -d wails-world -n wails-world -t react
Wails CLI v2.0.0-beta.42

Initialising Project 'wails-world'

Project Name:      wails-world
Project Directory: dev/wails-world
Project Template:  react
Template Support:

Initialised project 'wails-world' in 263ms.

Project Layout

Wails projects have the following layout:

├── build/
│   ├── appicon.png
│   ├── darwin/
│   └── windows/
├── frontend/
├── go.mod
├── go.sum
├── main.go
└── wails.json

Project structure rundown

  • /main.go - The main application
  • /frontend/ - Frontend project files
  • /build/- Project build directory
  • /build/appicon.png - The application icon
  • /build/darwin/ - Mac specific project files
  • /build/windows/ - Windows specific project files
  • /wails.json - The project configuration
  • /go.mod - Go module file
  • /go.sum - Go module checksum file

The default module name in go.mod is changeme. You should change this to something more appropriate.


To get started, run wails dev in the project directory:

cd wails-world
wails dev
Vite Server URL: http://localhost:3000/
  > Local: http://localhost:3000/
  > Network: use `--host` to expose

  ready in 330ms.

Wails Go React

Build the Application

From the project directory, run wails build. This will compile your project and save the production-ready binary in the build/bin directory.

Supported platforms:

darwinMacOS + architecture of build machine
darwin/amd64MacOS 10.13+ AMD64
darwin/arm64MacOS 11.0+ ARM64
darwin/universalMacOS AMD64+ARM64 universal application
windowsWindows 10/11 + architecture of build machine
windows/amd64Windows 10/11 AMD64
windows/arm64Windows 10/11 ARM64
linuxLinux + architecture of build machine
linux/amd64Linux AMD64
linux/arm64Linux ARM64
wails build -platform linux/amd64 -clean -o wails-world
App Type:               desktop
Platforms:              linux/amd64
Compiler:               /usr/bin/go
Build Mode:             Production
Skip Frontend:          false
Compress:               false
Package:                true
Clean Build Dir:        true
LDFlags:                ""
Tags:                   []
Race Detector:          false
Output File:            wails-world

Building target: linux/amd64
  - Installing frontend dependencies: Done.
  - Compiling frontend: Done.
  - Compiling application: Done.
  - Packaging application: Done.
Built 'dev/wails-world/build/bin/wails-world' in 28.931s.

You can execute the binary file directly ./build/bin/wails-world:

Wails Go React