From dd33dd15581dcb646e421730b30aa1576fefae35 Mon Sep 17 00:00:00 2001 From: taliesin-ai Date: Mon, 6 Jul 2026 16:38:05 +1000 Subject: [PATCH] docs(v3): rewrite the FAQ with accurate platform support and verified v3 commands The FAQ predated much of current v3 and had drifted badly: - Platform support said Windows 7+, macOS 10.13+ and Linux GTK3. Now matches the installation docs: Windows 10/11 (WebView2, AMD64/ARM64), macOS 10.15+/11+ (deploy target 10.13+), Linux GTK4 + WebKitGTK 6.0 default with the legacy gtk3 tag option, iOS/Android experimental, plus the server build. - Build answers used v2-style commands that do not exist in v3 (wails3 build -platform ..., manual -ldflags advice). Replaced with the real commands from the build guides (wails3 build GOOS=..., wails3 task darwin:build:universal, wails3 package) and a note that production defaults already strip binaries. - Removed the Electron comparison table in favour of stating what Wails does well on its own terms. - Every API snippet is now verified against v3 source and examples (GreetService bindings import, Events.On, app.Dialog.OpenFile chain, app.SystemTray.New) and every internal link resolves to an existing page. - Added the questions new users actually ask: prerequisites, wails3 doctor as the first troubleshooting step, build-failure checklist, how to report a bug. - Softened the production-readiness answer to point at the status page instead of overpromising. --- docs/src/content/docs/faq.mdx | 231 ++++++++++++++++------------------ 1 file changed, 106 insertions(+), 125 deletions(-) diff --git a/docs/src/content/docs/faq.mdx b/docs/src/content/docs/faq.mdx index e1e3e64c348..0fb69680db4 100644 --- a/docs/src/content/docs/faq.mdx +++ b/docs/src/content/docs/faq.mdx @@ -1,6 +1,6 @@ --- title: Frequently Asked Questions -description: Common questions about Wails +description: Answers to the most common questions about building applications with Wails v3 sidebar: order: 99 --- @@ -9,73 +9,90 @@ sidebar: ### What is Wails? -Wails is a framework for building desktop applications using Go and web technologies. It provides native OS integration whilst allowing you to build your UI with HTML, CSS, and JavaScript. +Wails is a framework for building desktop applications with Go and web technologies. Your application logic is written in Go, your interface is built with HTML, CSS, and JavaScript (or any frontend framework), and Wails renders it in the operating system's native webview. The result is a small, fast, native-feeling application: no bundled browser, low memory usage, and a single binary that typically weighs in around 10MB. -### How does Wails compare to Electron? +### What platforms does Wails support? -**Wails:** -- ~10MB memory usage -- ~15MB binary size -- Native performance -- Go backend +| Platform | Requirements | +|----------|--------------| +| Windows | Windows 10 and 11, AMD64 and ARM64. Uses WebView2, which ships with Windows 10/11 ([standalone installer](https://developer.microsoft.com/microsoft-edge/webview2/) for unusual setups). | +| macOS | 10.15+ on Intel (applications can target 10.13+), 11.0+ on Apple Silicon. Universal binaries are supported. | +| Linux | AMD64 and ARM64. The default stack is GTK4 with WebKitGTK 6.0 (Ubuntu 24.04+, Debian 13+, Fedora 40+ and similar). Distributions that only ship WebKit2GTK 4.1, such as Ubuntu 22.04, Debian 12 and RHEL 9, are supported via the legacy `-tags gtk3` build (available until v3.1). Distributions with only WebKit2GTK 4.0 are not supported. See the [Linux build guide](/guides/build/linux). | +| iOS and Android | Experimental. See the [mobile guides](/guides/mobile/). | -**Electron:** -- ~100MB+ memory usage -- ~150MB+ binary size -- Chromium overhead -- Node.js backend +You can also serve your application as a regular web app using the [server build](/guides/server-build). -### Is Wails production-ready? +Run `wails3 doctor` at any time to check your system and get platform-specific installation instructions. -Yes! Wails v3 is suitable for production applications. Many companies use Wails for their desktop applications. +### What do I need to get started? -### What platforms does Wails support? +- Go 1.25 or newer +- Node.js and npm (for the frontend build) +- Platform toolchain: WebView2 on Windows (preinstalled on 10/11), Xcode Command Line Tools on macOS, `gcc` plus GTK/WebKit development packages on Linux + +`wails3 doctor` checks all of this for you and tells you exactly what is missing. See [Installation](/quick-start/installation) for the full walkthrough. -- Windows (7+) -- macOS (10.13+) -- Linux (GTK3) +### Is Wails v3 production-ready? + +Wails v3 is in active pre-release. The API is stable and real applications are being built and shipped with it, but expect occasional rough edges while we finish the remaining polish. See the [project status page](/status) for the current picture. Wails v2 is the current stable release and continues to receive fixes. ## Development ### Do I need to know Go? -Basic Go knowledge is helpful but not required. You can start with simple services and learn as you go. +Basic Go knowledge helps but you do not need to be an expert. Application logic lives in plain Go methods, and the [tutorials](/tutorials/overview) walk you through everything else. Many developers pick up Go as they build their first Wails application. ### Can I use my favourite frontend framework? -Yes! Wails works with: -- Vanilla JavaScript -- React -- Vue -- Svelte -- Any framework that builds to HTML/CSS/JS +Yes. If it builds to HTML, CSS and JavaScript, it works with Wails. Templates ship for React, Vue, Svelte and vanilla JavaScript (each with TypeScript variants), and anything else can be wired up in minutes. See [Frontend Frameworks](/guides/dev/frontend-frameworks). ### How do I call Go functions from JavaScript? -Use bindings: +Register a service and Wails generates typed bindings for it: ```go // Go -func (s *Service) Greet(name string) string { +type GreetService struct{} + +func (g *GreetService) Greet(name string) string { return "Hello " + name } ``` ```javascript // JavaScript -import { Greet } from './bindings/changeme/service' -const message = await Greet("World") +import { GreetService } from "./bindings/changeme"; + +const message = await GreetService.Greet("World"); ``` +Bindings are regenerated automatically during `wails3 dev`, or on demand with `wails3 generate bindings`. See [Services](/features/bindings/services). + ### Can I use TypeScript? -Yes! Wails generates TypeScript definitions automatically. +Yes. The bindings generator produces TypeScript definitions for your services and their types, so calls into Go are fully typed. + +### How do I send events between Go and JavaScript? + +```go +// Go +app.Event.Emit("time", time.Now().Format(time.RFC1123)) +``` + +```javascript +// JavaScript +import { Events } from "@wailsio/runtime"; + +Events.On("time", (event) => { + console.log(event.data); +}); +``` + +Event names must match exactly. See the [Events Reference](/guides/events-reference). ### How do I debug my application? -Use your browser's dev tools: -- Right-click → Inspect Element -- Or enable dev tools in window options +Run `wails3 dev` and right-click in the window to open the browser dev tools, exactly as you would on the web. The dev server also supports hot reload of your frontend. See [Debugging](/guides/dev/debugging). ## Building & Distribution @@ -85,175 +102,139 @@ Use your browser's dev tools: wails3 build ``` -Your application will be in `bin/`. +Your binary lands in `bin/`. Production builds already apply the sensible defaults (build tags, `-trimpath`, stripped symbols), so no extra flags are needed for a lean binary. ### Can I cross-compile? -Yes! Build for other platforms: +Within limits. Pure Go cross-compilation does not apply because each platform uses native webview libraries, but there is good support for common cases: ```bash -wails3 build -platform windows/amd64 -wails3 build -platform darwin/universal -wails3 build -platform linux/amd64 -``` - -### How do I create an installer? +# Different architecture, same OS +wails3 build GOOS=windows GOARCH=arm64 -Use platform-specific tools: -- Windows: NSIS or WiX -- macOS: Create DMG -- Linux: DEB/RPM packages +# macOS universal binary +wails3 task darwin:build:universal +``` -See the [Installers Guide](/guides/installers). +Building for Linux from another OS uses a Docker-based toolchain. See [Cross-Platform Builds](/guides/build/cross-platform) for the full matrix. -### How do I code sign my application? +### How do I create an installer or package? -**macOS:** ```bash -codesign --deep --force --sign "Developer ID" MyApp.app +wails3 package ``` -**Windows:** -Use SignTool with your certificate. +This produces the platform-native format, and the [Installers guide](/guides/installers) covers NSIS on Windows, `.app` bundles and DMGs on macOS, and Linux packages. + +### How do I code sign my application? + +Both Windows and macOS signing (including notarization) are covered step by step in the [Signing guide](/guides/build/signing). ## Features ### Can I create multiple windows? -Yes! Wails v3 has native multi-window support: +Yes, multi-window support is native in v3: ```go window1 := app.Window.New() window2 := app.Window.New() ``` -### Does Wails support system tray? +See [Multiple Windows](/features/windows/multiple). + +### Does Wails support the system tray? -Yes! Create system tray applications: +Yes, including menus and click handlers: ```go -tray := app.SystemTray.New() -tray.SetIcon(iconBytes) -tray.SetMenu(menu) +systemTray := app.SystemTray.New() +systemTray.SetIcon(iconBytes) +systemTray.SetMenu(myMenu) ``` +See [System Tray](/features/menus/systray). + ### Can I use native dialogs? -Yes! Wails provides native dialogs: +Yes. File dialogs, message dialogs and question dialogs all use the native implementations: ```go -path, _ := app.Dialog.OpenFile(). +path, err := app.Dialog.OpenFile(). SetTitle("Select File"). PromptForSingleSelection() ``` -### Does Wails support auto-updates? +See [Dialogs](/features/dialogs/overview). -Yes — Wails v3 includes a built-in self-updater (`app.Updater`) with pluggable providers for GitHub Releases, keygen.sh, and Sparkle AppCast, cryptographic signature verification, and a default UI you can theme or replace. See the [In-App Updater](/guides/updater) guide and the [Self-Updating Wails App](/tutorials/04-self-update-a-wails-app) tutorial. +### Does Wails support auto-updates? -## Performance +Yes. Wails v3 includes a built-in self-updater (`app.Updater`) with pluggable providers for GitHub Releases, keygen.sh and Sparkle AppCast, cryptographic signature verification, and a default UI you can theme or replace. See the [In-App Updater](/guides/updater) guide and the [Self-Updating Wails App](/tutorials/04-self-update-a-wails-app) tutorial. -### Why is my binary large? +## Troubleshooting -Go binaries include the runtime. Reduce size: +### Something is not working. Where do I start? ```bash -wails3 build -ldflags "-s -w" +wails3 doctor ``` -### How do I improve performance? +It verifies your toolchain, lists missing dependencies with install commands, and prints the version information you should include in any bug report. -- Paginate large datasets -- Cache expensive operations -- Use events for updates -- Optimise frontend bundle -- Profile your code - -See the [Performance Guide](/guides/performance). - -### Does Wails support hot reload? - -Yes! Use dev mode: - -```bash -wails3 dev -``` +### My build fails -## Troubleshooting +The usual fixes, in order: -### My bindings aren't working +1. `go mod tidy` +2. `cd frontend && npm install` (a missing `node_modules` is the most common cause) +3. Update the CLI: `go install github.com/wailsapp/wails/v3/cmd/wails3@latest` +4. On Linux, check `wails3 doctor` for missing GTK/WebKit packages -Regenerate bindings: +### My bindings are missing or stale ```bash wails3 generate bindings ``` -### Window doesn't appear - -Check if you called `Show()`: - -```go -window := app.Window.New() -window.Show() // Don't forget this! -``` - -### Events not firing +Bindings regenerate automatically in dev mode; if you added a new service or changed method signatures outside of `wails3 dev`, regenerate them manually. -Ensure event names match exactly: +### Events are not firing -```go -// Go -app.Event.Emit("my-event", data) - -// JavaScript -OnEvent("my-event", handler) // Must match -``` +Event names must match exactly between `app.Event.Emit("name", ...)` in Go and `Events.On("name", ...)` in JavaScript. Check for typos and case differences first. -### Build fails +### I found a bug -Common fixes: -- Run `go mod tidy` -- Check `wails.json` configuration -- Verify frontend builds: `cd frontend && npm run build` -- Update Wails: `go install github.com/wailsapp/wails/v3/cmd/wails3@latest` +Please [open an issue](https://github.com/wailsapp/wails/issues) and include your `wails3 doctor` output. The [feedback guide](/feedback) explains what makes a report easy to act on. -## Migration +## Migrating from v2 ### Should I migrate from v2 to v3? -v3 offers: -- Better performance -- Multi-window support -- Improved API -- Better developer experience - -See the [Migration Guide](/migration/v2-to-v3). +v3 brings multi-window support, a cleaner services-based API, a built-in updater, a much more flexible build system, and better performance. New projects should start on v3. For existing projects, the [Migration Guide](/migration/v2-to-v3) walks through the differences. ### Will v2 be maintained? -Yes, v2 will receive critical updates. +Yes. v2 continues to receive fixes while v3 moves towards its stable release. ### Can I run v2 and v3 side by side? -Yes, they use different import paths. +Yes. The CLIs are separate binaries (`wails` and `wails3`) and the modules have different import paths, so projects on different major versions coexist happily on one machine. ## Community ### How do I get help? -- [Discord Community](https://discord.gg/JDdSxwjhGf) -- [GitHub Discussions](https://github.com/wailsapp/wails/discussions) -- [GitHub Issues](https://github.com/wailsapp/wails/issues) +- [Discord](https://discord.gg/JDdSxwjhGf) for quick questions and discussion +- [GitHub Discussions](https://github.com/wailsapp/wails/discussions) for longer-form questions +- [GitHub Issues](https://github.com/wailsapp/wails/issues) for bugs ### How do I contribute? -See the [Contributing Guide](/contributing). +See the [Contributing Guide](/contributing). Enhancements are discussed on Discord first; bug fixes are welcome any time. ### Where can I find examples? -- [Official Examples](https://github.com/wailsapp/wails/tree/master/v3/examples) -- [Community Examples](https://github.com/topics/wails) +The repository ships over 60 runnable examples covering windows, dialogs, events, the system tray, services and more: [v3/examples](https://github.com/wailsapp/wails/tree/master/v3/examples). ## Still Have Questions?