1# Wails desktop apps
 2
 3Read [baseline.md](baseline.md), [mise.md](mise.md), [web.md](web.md),
 4[packaging.md](packaging.md), [testing.md](testing.md), and
 5[preferred-libraries.md](preferred-libraries.md) before applying these Wails
 6specifics.
 7
 8Use Wails when the app is a desktop product, not merely because it has a web
 9view. Go should own application logic; the frontend should render state and call
10bindings.
11
12## Build/tooling
13
14Start from the baseline in [mise.md](mise.md); keep its fmt, modernize, lint,
15vuln, race-enabled test, and check tasks. Then add Wails/frontend tools and
16tasks in mise, not Taskfile:
17
18```toml
19[tools]
20go = "latest"
21node = "22"
22"go:github.com/wailsapp/wails/v2/cmd/wails" = "latest"
23"go:golang.org/x/vuln/cmd/govulncheck" = "latest"
24golangci-lint = "latest"
25nfpm = "latest"
26
27[env]
28_.path = ["{{config_root}}/frontend/node_modules/.bin"]
29
30[vars]
31wails_build_args = "-tags webkit2_41 -trimpath"
32wails_ldflags = "-s -w"
33
34[tasks.dev]
35run = "wails dev -tags webkit2_41"
36
37[tasks.build]
38run = '''
39wails build {{vars.wails_build_args}} -ldflags "{{vars.wails_ldflags}}"
40'''
41```
42
43On Linux, include `-tags webkit2_41` for WebKitGTK 4.1. Missing it often fails
44late and unclearly.
45
46If the app exposes an About/version surface or release metadata, choose a
47project-owned version policy and inject the resolved value with `-X`, as in the
48CLI guidance.
49
50## Frontend stack
51
52Use the existing package manager if one exists. Ask before introducing a new one.
53Use Svelte 5 + TypeScript + Vite for Wails frontends. Tailwind and shadcn-svelte
54are optional project choices, not defaults to add blindly.
55
56Frontend checks usually split from backend checks:
57
58- backend: `golangci-lint fmt`, `golangci-lint run --fix`, `govulncheck`, tests
59- frontend: typecheck, lint, format, unit tests when present
60- combined: `mise run check`
61
62## Binding and event rules
63
64- Do not edit generated `frontend/wailsjs/` files.
65- Add Go methods/types to trigger Wails TypeScript generation.
66- Prefer explicit event names and typed payloads for async pipelines.
67- Go owns queues, cancellation, filesystem access, keyring access, and API
68  clients.
69- Svelte owns local rendering state and user interactions.
70
71## Errors
72
73For user-facing backend errors, send a structured shape the frontend can render:
74code, message, optional suggestion, optional details. Do not make the frontend
75parse arbitrary English when the backend can categorise the failure.
76
77## Packaging
78
79Read [packaging.md](packaging.md) for nFPM, desktop files, icons, and WebKit
80dependencies.