216 lines
7.1 KiB
Text
216 lines
7.1 KiB
Text
---
|
||
title: Codebase Layout
|
||
description: How the Wails v3 repository is organised and how the pieces fit together
|
||
sidebar:
|
||
order: 2
|
||
---
|
||
|
||
Wails v3 lives in a **monorepo** that contains the framework runtime, CLI,
|
||
examples, documentation, and build tool-chain.
|
||
This page walks through the *directory structure* that matters to anyone digging
|
||
into the internals.
|
||
|
||
## Top-Level View
|
||
|
||
```
|
||
wails/
|
||
├── v3/ # ⬅️ Everything specific to Wails v3 lives here
|
||
├── v2/ # Legacy v2 implementation (can be ignored for v3 work)
|
||
├── docs/ # Astro-powered v3 docs site (this page!)
|
||
├── website/ # Docusaurus v2 site and marketing pages (main site)
|
||
├── scripts/ # Misc helper scripts (e.g. sponsor image generator)
|
||
├── mkdocs-website/ # Deprecated v3 docs prototype
|
||
└── *.md # Project-wide meta files (CHANGELOG, LICENSE, …)
|
||
```
|
||
|
||
From here on, we zoom into the **`v3/`** tree.
|
||
|
||
## `v3/` Root
|
||
|
||
```
|
||
v3/
|
||
├── cmd/ # Compilable commands (currently only wails3 CLI)
|
||
├── examples/ # Hands-on sample apps testing every feature
|
||
├── internal/ # Framework implementation (not public API)
|
||
├── pkg/ # Public Go packages ‑ the API surface
|
||
├── tasks/ # Taskfile-based release utilities
|
||
├── templates/ # RFC-style proposals (WEP) + common assets
|
||
├── go.mod
|
||
└── go.sum
|
||
```
|
||
|
||
### Mental Model
|
||
|
||
1. **`pkg/`** exposes *what application developers import*
|
||
2. **`internal/`** contains *how the magic is implemented*
|
||
3. **`cmd/wails3`** drives *project lifecycle & builds*
|
||
4. **`examples/`** double as *living tests* and *reference code*
|
||
|
||
Everything else supports those three pillars.
|
||
|
||
---
|
||
|
||
## `cmd/` – Commands
|
||
|
||
| Path | Notes |
|
||
|------|-------|
|
||
| `v3/cmd/wails3` | The **CLI entrypoint**. A tiny `main.go` delegates all logic to packages in `internal/commands`. |
|
||
| `internal/commands/*` | Sub-commands (init, dev, build, doctor, …). Each lives in its own file for easy discoverability. |
|
||
| `internal/commands/task_wrapper.go` | Bridges between CLI flags and the Taskfile build pipeline. |
|
||
|
||
The CLI owns:
|
||
|
||
* **Project scaffolding** (`init`, template generation)
|
||
* **Dev server orchestration** (`dev`, live-reload)
|
||
* **Production builds & packaging** (`build`, `package`, platform wrappers)
|
||
* **Diagnostics** (`doctor`)
|
||
|
||
---
|
||
|
||
## `internal/` – The Engine Room
|
||
|
||
```
|
||
internal/
|
||
├── assetserver/ # Serving & embedding web assets
|
||
├── buildinfo/ # Reproducible build metadata
|
||
├── commands/ # CLI mechanics (see above)
|
||
├── runtime/ # Desktop runtime (per-platform)
|
||
├── generator/ # Static analysis & binding generator
|
||
├── templates/ # Project templates (frontend stacks)
|
||
├── packager/ # Linux AppImage/deb/rpm, Windows MSI, macOS DMG
|
||
├── capabilities/ # Host OS capability probing
|
||
├── dbus/ # Linux system tray integration
|
||
├── service/ # IPC micro-services framework
|
||
└── ... # [other helper sub-packages]
|
||
```
|
||
|
||
### Key Sub-Packages
|
||
|
||
| Package | Responsibility | Where It Connects |
|
||
|---------|----------------|-------------------|
|
||
| `runtime` | Window/event loop, clipboard, dialogs, system tray. One file per OS with build-tags (`*_darwin.go`, `*_linux.go`, …). | Called by `pkg/application` and message processor. |
|
||
| `assetserver` | Dual-mode file server:<br />• Dev: serves from disk & proxies Vite<br />• Prod: embeds assets via `go:embed` | Initialized by `pkg/application` during startup. |
|
||
| `generator` | Parses Go source to build **binding metadata** which later produces TypeScript stub files and Go marshal/unmarshal code. | Triggered by `wails3 init` / `wails3 generate`. |
|
||
| `packager` | Wraps platform-specific packaging CLIs (eg. `electron-builder` equivalents) into Go for cross-platform automation. | Invoked by `wails3 package`. |
|
||
|
||
Supporting utilities (eg. `s/`, `hash/`, `flags/`) keep internal concerns decoupled.
|
||
|
||
---
|
||
|
||
## `pkg/` – Public API
|
||
|
||
```
|
||
pkg/
|
||
├── application/ # Core API: windows, menus, dialogs, events, …
|
||
├── runtime/ # JS-side helpers (bridge, events, screen, ...)
|
||
├── options/ # Strongly-typed configuration structs
|
||
├── menu/ # Declarative menu DSL
|
||
└── ... # Platform helpers (mac/, windows/, assetserver/, …)
|
||
```
|
||
|
||
`pkg/application` bootstraps a Wails program:
|
||
|
||
```go
|
||
func main() {
|
||
app := application.New(application.Options{
|
||
Name: "MyApp",
|
||
Assets: application.NewAssetsFS(assetsFS),
|
||
})
|
||
window := app.Window.New(&application.WebviewWindowOptions{
|
||
Title: "Hello",
|
||
Width: 1024,
|
||
Height: 768,
|
||
})
|
||
app.Run()
|
||
}
|
||
```
|
||
|
||
Under the hood it:
|
||
|
||
1. Spins up `internal.runtime.*`
|
||
2. Sets up an `assetserver`
|
||
3. Registers bindings generated by `internal.generator`
|
||
4. Enters the OS main thread
|
||
|
||
---
|
||
|
||
## `examples/` – Living Specs
|
||
|
||
Each sub-folder is a **self-contained application** exercising one feature.
|
||
Patterns you’ll see mirrored in real code:
|
||
|
||
* Binding services (`examples/binding/`)
|
||
* Multi-window (`examples/window/`)
|
||
* System tray (`examples/systray-*`)
|
||
* Packaging (`examples/file-association/`)
|
||
|
||
When in doubt, start here and drill into implementation.
|
||
|
||
---
|
||
|
||
## `templates/` – Scaffolding Blueprints
|
||
|
||
`internal/templates` ships **base templates** (Go layout) and **frontend skins**
|
||
(React, Svelte, Vue, …).
|
||
At `wails3 init -t react`, the CLI:
|
||
|
||
1. Copies `_common` Go files
|
||
2. Merges desired frontend pack
|
||
3. Runs `npm install` + `task deps`
|
||
|
||
Editing templates **does not** affect existing apps, only future `init`s.
|
||
|
||
---
|
||
|
||
## `tasks/` – Release Automation
|
||
|
||
Taskfiles wrap complex cross-compilation, version bumping, and changelog
|
||
generation. They are consumed programmatically by `internal/commands/task.go`
|
||
so the same logic powers **CLI** and **CI**.
|
||
|
||
---
|
||
|
||
## How the Pieces Interact
|
||
|
||
```d2
|
||
direction: down
|
||
CLI: "wails3 CLI"
|
||
Generator: "internal/generator"
|
||
AssetDev: "assetserver (dev)"
|
||
Packager: "internal/packager"
|
||
AppRuntime: {
|
||
label: "App runtime"
|
||
ApplicationPkg: "pkg.application"
|
||
InternalRuntime: "internal.runtime"
|
||
OSAPIs: "OS APIs"
|
||
}
|
||
CLI -> Generator: "build / generate"
|
||
CLI -> AssetDev: "dev"
|
||
CLI -> Packager: "package"
|
||
Generator -> ApplicationPkg: "bindings"
|
||
ApplicationPkg -> InternalRuntime
|
||
InternalRuntime -> OSAPIs
|
||
ApplicationPkg -> AssetDev
|
||
```
|
||
|
||
*CLI → generator → runtime* forms the core path from **source** to **running
|
||
desktop app**.
|
||
|
||
---
|
||
|
||
## Orientation Tips
|
||
|
||
| Need to understand… | Look at… |
|
||
|---------------------|----------|
|
||
| Platform shims | `internal/runtime/*_DARWIN.go`, `*_windows.go`, … |
|
||
| Bridge protocol | `pkg/application/messageprocessor_*.go` |
|
||
| Asset workflow | `internal/assetserver`, `v3/templates/base/assets` |
|
||
| Packaging flow | `internal/commands/appimage.go`, `internal/packager` |
|
||
| Template engine | `internal/templates/templates.go` |
|
||
| Static analysis | `internal/generator/*` |
|
||
|
||
---
|
||
|
||
You now have a **mental map** of the repository.
|
||
Use it with `ripgrep`, your IDE’s “Go to File/Symbol”, and the example apps to
|
||
navigate deeper into any feature. Happy hacking!
|