Skip to content

docs(v3): rewrite the FAQ with accurate platform support and verified v3 commands #5763

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leaanthony merged 1 commit into from
Jul 6, 2026
+106 −125
Merged

docs(v3): rewrite the FAQ with accurate platform support and verified v3 commands #5763

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 106 additions & 125 deletions docs/src/content/docs/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---
Expand All @@ -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

Expand All @@ -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?

Expand Down
Loading