95 lines
3.5 KiB
Text
95 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!
|