From 715a2b09436b6a579b53c96c21cb9f7a365f69d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zolt=C3=A1n=20Papp?= Date: Mon, 15 Jun 2026 13:19:45 +0200 Subject: [PATCH] docs(contributing): update UI build guidelines for Wails v3 The UI client migrated from Fyne to Wails v3 + React. Update the Requirements and Build sections accordingly, fix the Windows installer UI build command to use the task runner, bump the Go version to 1.25, and drop the now-redundant client/ui/README.md. --- CONTRIBUTING.md | 53 +++++++++++++++++++++--- client/ui/README.md | 99 --------------------------------------------- 2 files changed, 47 insertions(+), 105 deletions(-) delete mode 100644 client/ui/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3361c6f72..261083783 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,13 +79,21 @@ dependencies are installed. Here is a short guide on how that can be done. ### Requirements -#### Go 1.21 +#### Go 1.25 Follow the installation guide from https://go.dev/ -#### UI client - Fyne toolkit +#### UI client - Wails v3 + React -We use the fyne toolkit in our UI client. You can follow its requirement guide to have all its dependencies installed: https://developer.fyne.io/started/#prerequisites +The desktop UI client (`client/ui`) is built with [Wails v3](https://v3.wails.io/) and a React frontend rendered in a WebView. To build it you need: + +- Go ≥ 1.25 +- Node ≥ 20 and **pnpm** (`corepack enable && corepack prepare pnpm@latest --activate`) +- The `wails3` CLI: `go install github.com/wailsapp/wails/v3/cmd/wails3@latest` +- The `task` runner: `go install github.com/go-task/task/v3/cmd/task@latest` +- Linux only: `libwebkitgtk-6.0-dev`, `libgtk-4-dev`, `libsoup-3.0-dev` + +All UI build, dev-loop, and cross-compile commands are described in the [UI client](#ui-client) section below. #### gRPC You can follow the instructions from the quickstarter guide https://grpc.io/docs/languages/go/quickstart/#prerequisites and then run the `generate.sh` files located in each `proto` directory to generate changes. @@ -214,6 +222,39 @@ To start NetBird the client in the foreground: sudo ./client up --log-level debug --log-file console ``` > On Windows use a powershell with administrator privileges + +#### UI client + +The desktop UI lives in `client/ui` and is built with Wails v3 (see [Requirements](#ui-client---wails-v3--react)). All commands run from `client/ui`. + +Live-reload development (Vite + Go binary + `*.go` watcher): + +``` +cd client/ui +task dev +``` + +Pass daemon flags after `--`: + +``` +task dev -- --daemon-addr=tcp://127.0.0.1:41731 +``` + +Production build (frontend assets embedded into the binary, output in `client/ui/bin/`): + +``` +cd client/ui +task build +``` + +Cross-compile the Windows binary from Linux (requires the mingw-w64 toolchain, e.g. `sudo apt install gcc-mingw-w64-x86-64`): + +``` +CGO_ENABLED=1 task windows:build +``` + +> macOS cross-compile from Linux is not supported (signing and notarization need a real Mac). + #### Signal service To start NetBird's signal, execute: @@ -251,10 +292,10 @@ Create dist directory mkdir -p dist/netbird_windows_amd64 ``` -UI client +UI client (built with Wails v3 — see the [UI client](#ui-client) section above) ```shell -CC=x86_64-w64-mingw32-gcc CGO_ENABLED=1 GOOS=windows GOARCH=amd64 go build -o netbird-ui.exe -ldflags "-s -w -H windowsgui" ./client/ui -mv netbird-ui.exe ./dist/netbird_windows_amd64/ +(cd client/ui && CGO_ENABLED=1 task windows:build) +mv client/ui/bin/netbird-ui.exe ./dist/netbird_windows_amd64/ ``` Client diff --git a/client/ui/README.md b/client/ui/README.md deleted file mode 100644 index 4aeac55ab..000000000 --- a/client/ui/README.md +++ /dev/null @@ -1,99 +0,0 @@ -# NetBird desktop UI (Wails3 + React) - -Replaces `client/ui` (Fyne). One binary on Windows / macOS / Linux, -talks to the NetBird daemon over gRPC, renders a React frontend in a -WebView. - -## Prerequisites - -- Go ≥ 1.25, Node ≥ 20, **pnpm** (`corepack enable && corepack prepare pnpm@latest --activate`) -- `wails3` CLI: `go install github.com/wailsapp/wails/v3/cmd/wails3@latest` -- `task`: `go install github.com/go-task/task/v3/cmd/task@latest` -- A running NetBird daemon (default: `unix:///var/run/netbird.sock`, - Windows `tcp://127.0.0.1:41731`) -- Linux only: `libwebkitgtk-6.0-dev`, `libgtk-4-dev`, `libsoup-3.0-dev` - -## Develop without rebuilding - -```bash -cd client/ui -task dev -``` - -`task dev` runs Vite (port 9245) + the Go binary + a `*.go` watcher. -Frontend edits hot-reload instantly. Go edits trigger a rebuild and -relaunch. Pass daemon flags after `--`: - -```bash -task dev -- --daemon-addr=tcp://127.0.0.1:41731 -``` - -For pure UI work (no native window, fastest loop): - -```bash -cd frontend && pnpm dev -``` - -## Production build - -```bash -task build -``` - -Output in `bin/`. Frontend assets are embedded into the binary. - -### Cross-compile Windows from Linux - -Install the mingw-w64 toolchain once: - -```bash -sudo apt install gcc-mingw-w64-x86-64 # Debian/Ubuntu -sudo dnf install mingw64-gcc # Fedora -sudo pacman -S mingw-w64-gcc # Arch -``` - -Then: - -```bash -CGO_ENABLED=1 task windows:build -``` - -Produces `bin/netbird-ui.exe`. macOS cross-compile from Linux is not -supported (signing and notarization need a real Mac). - -### Windows console build (logs in the terminal) - -Default `windows:build` links the binary as a Windows GUI app, which -detaches from the launching console — `logrus` output, `fmt.Println`, -and panics go nowhere visible. To debug tray/event/daemon issues: - -```bash -CGO_ENABLED=1 task windows:build:console -``` - -Produces `bin/netbird-ui-console.exe`. Run it from `cmd.exe` / -PowerShell / Windows Terminal and stdout/stderr land in that -terminal. Same flag works on a native Windows build (drop the -`CGO_ENABLED=1` if your toolchain already has it set). - -## Regenerating bindings - -When a Go service signature changes: - -```bash -wails3 generate bindings -``` - -`task dev` does this automatically on `*.go` save. - -## Tray icons - -Source SVGs live in `assets/svg/` (state.svg + state-macos.svg). After editing -any SVG, rasterize to the PNGs the Go side embeds: - -```bash -task common:generate:tray:icons -``` - -Requires Inkscape. Commit the resulting `assets/*.png` files alongside the -SVG change so CI doesn't need Inkscape installed.