96 lines
3.5 KiB
Text
96 lines
3.5 KiB
Text
|
---
|
|||
|
|
title: Technical Overview
|
|||
|
|
description: High-level architecture and roadmap to the Wails v3 codebase
|
|||
|
|
sidebar:
|
|||
|
|
order: 1
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
import { Card, CardGrid } from "@astrojs/starlight/components";
|
|||
|
|
|
|||
|
|
## 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
|
|||
|
|
|
|||
|
|
<CardGrid>
|
|||
|
|
<Card title="Go Backend" icon="seti:go">
|
|||
|
|
The heart of every Wails app is Go code compiled into a native executable.
|
|||
|
|
It owns application logic, system integration and performance-critical
|
|||
|
|
operations.
|
|||
|
|
</Card>
|
|||
|
|
|
|||
|
|
<Card title="Web Frontend" icon="seti:html">
|
|||
|
|
UI is written with standard web tech (React, Vue, Svelte, Vanilla, …)
|
|||
|
|
rendered by a lightweight system WebView (WebKit on Linux/macOS, WebView2 on
|
|||
|
|
Windows).
|
|||
|
|
</Card>
|
|||
|
|
|
|||
|
|
<Card title="Bridging Layer" icon="puzzle">
|
|||
|
|
A zero-copy, in-memory bridge enables **Go⇄JavaScript** calls with automatic
|
|||
|
|
type conversion, event propagation and error forwarding.
|
|||
|
|
</Card>
|
|||
|
|
|
|||
|
|
<Card title="CLI & Tooling" icon="terminal">
|
|||
|
|
`wails3` orchestrates project creation, live-reload dev server, asset
|
|||
|
|
bundling, cross-compilation and packaging (deb, rpm, AppImage, msi, dmg…).
|
|||
|
|
</Card>
|
|||
|
|
</CardGrid>
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Architectural Overview
|
|||
|
|
|
|||
|
|
**Wails v3 – End-to-End Flow**
|
|||
|
|
|
|||
|
|
{/*
|
|||
|
|
TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
|
|||
|
|
The previous D2 code block was causing MDX parsing errors in the build pipeline.
|
|||
|
|
*/}
|
|||
|
|
|
|||
|
|
**[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 `wails 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.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
:::note
|
|||
|
|
Prerequisites: You should be comfortable with **Go 1.25+**, basic TypeScript,
|
|||
|
|
and modern frontend build tools. If you are new to Go, consider skimming the
|
|||
|
|
official tour first.
|
|||
|
|
:::
|
|||
|
|
|
|||
|
|
Happy exploring — and welcome to the Wails v3 internals!
|