Technical Overview

Welcome to the Wails v3 Technical Documentation

This section is not about community guidelines or how to open a pull-request. Instead, it dives into how Wails v3 is built so that you can quickly orient yourself in the codebase and start hacking with confidence.

Whether you plan to patch the runtime, extend the CLI, craft new templates, or simply understand the internals, the pages that follow provide the technical context you need.

High-Level Architecture

Go Backend

The heart of every Wails app is Go code compiled into a native executable. It owns application logic, system integration and performance-critical operations.

Web Frontend

UI is written with standard web tech (React, Vue, Svelte, Vanilla, …) rendered by a lightweight system WebView (WebKit on Linux/macOS, WebView2 on Windows).

Bridging Layer

A zero-copy, in-memory bridge enables Go⇄JavaScript calls with automatic type conversion, event propagation and error forwarding.

CLI & Tooling

wails3 orchestrates project creation, live-reload dev server, asset bundling, cross-compilation and packaging (deb, rpm, AppImage, msi, dmg…).

Architectural Overview

Wails v3 – End-to-End Flow

[End-to-End Flow Diagram Placeholder]

The diagram shows the end-to-end flow:

  1. CLI drives generation, dev server, compilation, and packaging.
  2. Binding System produces glue code that lets the Web Frontend call into the Go Backend.
  3. During development the Asset Server proxies to the framework dev server; in production it serves embedded files.
  4. At runtime the Desktop Runtime manages windows and OS APIs, while the Bridge shuttles messages between Go and JavaScript.

What This Documentation Covers

Topic Why It Matters
Codebase Layout Map of /v3 directories and how modules interact.
Runtime Internals Window management, system APIs, message processor, and platform shims.
Asset & Dev Server How web assets are served in dev and embedded in production.
Build & Packaging Pipeline Taskfile-based workflow, cross-platform compilation, and installer generation.
Binding System Static analysis pipeline that generates type-safe Go⇄TS bindings.
Template System Generator architecture that powers wails3 init -t <framework>.
Testing & CI Unit/integration test harness, GitHub Actions, race detector guidance.
Extending Wails Adding services, templates, or CLI sub-commands.

Each subsequent page drills into these areas with concrete code samples, diagrams, and references to the relevant source files.

Happy exploring — and welcome to the Wails v3 internals!

Edit page

Last updated: