Build a Desktop App with Wails #1: What Wails Is — Lightweight Desktop Apps in Go
Once you have the fundamentals of Go down from the Go Basics course, most hands-on practice leads to web servers and CLIs. But servers are not the only thing you can build with Go. There are moments when you need a desktop app with a window — a small utility for your team, a tool that works with local files, an in-house dashboard client. Wails is the framework that lets you take your Go code and your web frontend skills straight to the desktop.
It runs in eight parts (six main plus two deep-dives).
- #1 What Wails is — lightweight desktop apps in Go ← this post
- #2 Project structure and the dev loop — wails dev and bindings
- #3 Connecting Go and the frontend — method bindings and events
- #4 System integration — dialogs, menus, and window control
- #5 Real-world features — persisting settings and error handling
- #6 Build and distribution — packaging per platform
- #7 Adding a frontend framework — Svelte, Vue, React (deep-dive)
- #8 Debugging — dev tools, logs, common errors (deep-dive)
This post starts by locating Wails on the map of desktop app frameworks, then walks through installation and the environment check, and finishes by opening the window of your first app.
The desktop app framework landscape #
Building desktop apps with web technology is already mainstream. VS Code, Slack, and Discord all take this approach. Comparing the three main options makes it clear where Wails stands.
| Electron | Tauri | Wails | |
|---|---|---|---|
| Backend language | Node.js | Rust | Go |
| Rendering | Chromium bundled into the app | OS built-in WebView | OS built-in WebView |
| Distribution size | Tens to hundreds of MB | A few MB | A few MB |
| Memory usage | Large (Chromium processes) | Small | Small |
| Ecosystem maturity | Largest | Large | Growing |
Electron ships the entire Chromium browser inside the app. It guarantees identical rendering on every OS, but even a simple note-taking app ends up with an installer over 100MB and a large memory footprint. Tauri and Wails take the opposite approach. They borrow the WebView already built into the OS (WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux), which shrinks the distribution down to a few megabytes.
The difference between Tauri and Wails is the backend language. Tauri uses Rust, Wails uses Go. If you already write Go, being able to bring goroutines, the standard library, and your existing Go code directly into the backend of a desktop app is the reason to pick Wails.
How a Wails app is structured #
A Wails app consists of two layers.
┌─────────────── Native window ──────────────┐
│ │
│ Web frontend (HTML/CSS/JS, WebView) │
│ Rendering, user input │
│ │
│ ▲ calls │ results/events│
│ │ ▼ │
│ Go backend (single binary) │
│ Files, network, business logic │
└────────────────────────────────────────────┘The UI is drawn with web technology, and everything a browser cannot do — file access, heavy computation — is handled by Go. The two layers are connected by bindings that Wails generates automatically, so JavaScript on the frontend can call Go methods as if they were ordinary functions. This connection is the core concept running through the whole series, and #3 covers it in detail.
The build output is a single executable with the frontend assets embedded. No separate runtime to install — you hand over one file and it runs.
v2 and v3 — the baseline for this series #
Wails v2 is the current stable release, and the next version, v3, is in alpha as of July 2026. v3 promises multi-window support and a new API structure and is under active development, but no official release date has been announced. This series is based on the stable v2, and the final part wraps up with an outlook on what changes in v3.
Installation and diagnosis #
You need Go 1.21 or later and npm. The Wails CLI installs with a single go install.
go install github.com/wailsapp/wails/v2/cmd/wails@latestDesktop apps have OS-specific dependencies, so it is worth running the diagnostic command right after installation.
$ wails doctor
Wails CLI v2.10.1
...
# Diagnosis
Your system is ready for Wails development!wails doctor shows the installation status of Go, npm, and the platform dependencies in a table, and even tells you how to install anything that is missing. When the last line says ready, you are set.
webkit2gtk family) depending on your distribution, and wails doctor tells you the exact package names.Running the first app #
Now create a project and open a window. Pass a project name and a template to wails init.
wails init -n hello-wails -t vanilla
cd hello-wails
wails devThe first run takes a little while because it installs and builds the frontend dependencies. When it finishes, a native window opens with a starter app that greets you by the name you type into the input field. It looks like an ordinary web page, but the greeting is produced not by JavaScript in a browser — it comes from the Go code running behind the window.
-t vanilla selects the plain HTML/JS template with no framework. React, Vue, and Svelte templates are also available, and the next post opens up the template options and the project structure one piece at a time.
Wrapping up #
This post comes down to three points.
- Wails is a desktop framework that combines a Go backend and a web frontend in a single native window.
- Unlike Electron, it uses the OS built-in WebView, so the distribution is a single executable of just a few megabytes.
- v2 is stable and v3 is in alpha, so this series is based on v2.
In the next post, “Build a Desktop App with Wails #2: Project Structure and the Dev Loop — wails dev and Bindings”, we open the files that wails init created, confirm what each one does, and take a first look at the hot-reload dev loop and how bindings work.