wails

name	wails
description	Wails v2 Go desktop apps with web frontend. This skill should be used when scaffolding, binding Go to JS, configuring options, building cross-platform, or debugging webkit2gtk/WebView2 rendering.
last_updated	"2026-04-18T00:00:00.000Z"
wails_version	v2.9
source	https://github.com/wailsapp/wails/tree/master/website/docs

Wails v2 - Go Desktop Apps with Web UI

Quick Start

# Install CLI
go install github.com/wailsapp/wails/v2/cmd/wails@latest

# Check dependencies
wails doctor

# Create project (default: svelte)
wails init -n myapp -t svelte-ts

# Development with hot-reload
cd myapp && wails dev

# Production build
wails build

Architecture

┌─────────────────────────────────────┐
│          Desktop Window             │
│  ┌───────────────────────────────┐  │
│  │   WebView (webkit2gtk/WebView2)│  │
│  │   ┌─────────────────────────┐ │  │
│  │   │  Frontend (Svelte/React │ │  │
│  │   │  /Vue/Preact/Lit/Vanilla│ │  │
│  │   └──────────┬──────────────┘ │  │
│  └──────────────┼────────────────┘  │
│                 │ IPC (JSON-RPC)     │
│  ┌──────────────┴────────────────┐  │
│  │  Go Backend                   │  │
│  │  - Bound methods → JS funcs  │  │
│  │  - Runtime API               │  │
│  │  - Lifecycle callbacks       │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Method binding: Go structs with exported methods → wails.Bind() → auto-generated TypeScript in frontend/wailsjs/. Frontend calls Go methods as async JS functions. Structs used as params/returns get TS models generated.

Runtime API: runtime package provides window control, events (emit/on), dialogs (open/save/message), clipboard, screen info, notifications, drag-drop, browser open, environment, log, menu updates.

Lifecycle callbacks: OnStartup(ctx) → OnDomReady(ctx) → app runs → OnBeforeClose(ctx) bool → OnShutdown(ctx). Context from OnStartup used for runtime calls.

Project Layout

myapp/
├── main.go              # Entry point, wails.Run() with options
├── app.go               # App struct with bound methods
├── wails.json           # Project config (name, frontend:build/install, author)
├── go.mod
├── frontend/
│   ├── src/             # Frontend source (framework-specific)
│   ├── index.html
│   ├── package.json
│   └── wailsjs/         # Auto-generated bindings (DO NOT EDIT)
│       ├── go/          # Go method wrappers as JS
│       └── runtime/     # Runtime API TS definitions
├── build/
│   ├── appicon.png      # App icon
│   ├── darwin/          # macOS-specific (Info.plist)
│   ├── windows/         # Windows-specific (wails.exe.manifest, NSIS config)
│   └── bin/             # Build output

Application Options (main.go)

wails.Run(&options.App{
    Title:            "My App",
    Width:            1024,
    Height:           768,
    MinWidth:         400,
    MinHeight:        300,
    Frameless:        false,
    StartHidden:      false,
    AlwaysOnTop:      false,
    BackgroundColour: &options.RGBA{R: 27, G: 38, B: 54, A: 1},
    OnStartup:        app.startup,
    OnShutdown:       app.shutdown,
    OnDomReady:       app.domReady,
    OnBeforeClose:    app.beforeClose,
    Bind:             []interface{}{app},
    // Platform-specific
    Windows: &windows.Options{},
    Mac:     &mac.Options{},
    Linux:   &linux.Options{},
})

wails.json Config

{
  "name": "myapp",
  "outputfilename": "myapp",
  "frontend:install": "npm install",
  "frontend:build": "npm run build",
  "frontend:dev:watcher": "npm run dev",
  "frontend:dev:serverUrl": "auto",
  "author": { "name": "Dev", "email": "[e-mail]" }
}

Key CLI Commands

Command	Purpose
wails init -n NAME -t TEMPLATE	Create new project
wails dev	Dev mode with hot-reload
wails build	Production build
wails build -nsis	Windows NSIS installer
wails build -platform darwin/universal	macOS universal binary
wails build -tags webkit2_41	Ubuntu 24.04+ webkit support
wails generate module	Regenerate frontend bindings
wails doctor	Check system dependencies

References

• Installation & Dependencies
• Project Setup & Templates
• Background Transparency & Browser vs Wails Rendering