wails3
Build, debug, and package Wails v3 desktop apps (module github.com/wailsapp/wails/v3, a prerelease) that pair a Go backend with a web frontend: application.New and its Options, services registered with application.NewService and their startup and shutdown hooks, bindings from wails3 generate bindings, errors and panics as rejected promises, typed events, dialogs, windows, embedded assets, the wails3 CLI and Taskfile, server mode, and cgo with GTK4 and WebKitGTK 6.0 on Linux. Use when writing or changing a Wails v3 app, adding a service method, or debugging a v3 build, binding, or blank window. Not for Wails v2 (module github.com/wailsapp/wails/v2; use the wails2 skill), Electron or Tauri apps, or Go web servers.
tpscloud · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add tpscloud/gophers --skill wails3技能说明
name: wails3 description: "Build, debug, and package Wails v3 desktop apps (module github.com/wailsapp/wails/v3, a prerelease) that pair a Go backend with a web frontend: application.New and its Options, services registered with application.NewService and their startup and shutdown hooks, bindings from wails3 generate bindings, errors and panics as rejected promises, typed events, dialogs, windows, embedded assets, the wails3 CLI and Taskfile, server mode, and cgo with GTK4 and WebKitGTK 6.0 on Linux. Use when writing or changing a Wails v3 app, adding a service method, or debugging a v3 build, binding, or blank window. Not for Wails v2 (module github.com/wailsapp/wails/v2; use the wails2 skill), Electron or Tauri apps, or Go web servers." license: "MIT"
Wails v3
Wails v3 runs a Go backend and a web frontend in native windows. You create
the app with application.New, register Go structs as services, open windows
through app.Window, and reach dialogs and events through managers on the
app (app.Dialog, app.Event). The exported methods of each service become
promise-returning functions in generated TypeScript or JavaScript. v3 is a
prerelease, its API changes between betas, and it shares almost no API with
v2, so most bugs come from code written for v2 or for a different beta.
Workflow
- Read
go.mod. If it requiresgithub.com/wailsapp/wails/v2, stop and use thewails2skill; without it, read the pinned v2 module source. v2 and v3 APIs do not mix, so do not migrate between majors, or move to another v3 beta, unless asked. If the project pins a v3 version other than the one in Sources, read that version's source before trusting a detail here:go doc github.com/wailsapp/wails/v3/pkg/application, or the module cache under$(go env GOMODCACHE)/github.com/wailsapp/wails/v3@<version>. - Find
application.New(application.Options{...}), the services, the windows, the//go:embedasset directory, and how the project builds:Taskfile.ymlwith thewails3CLI, or plaingo buildfrom a script. Keep the existing workflow. - Change the Go side first, following The service contract. For generated bindings, the JavaScript runtime, and frontend tests, see references/frontend.md.
- For build tags, cgo, Linux libraries, the Taskfile, and server mode, see references/building.md.
- Before finishing, run Verify.
Telling v3 from v2
| Concern | Wails v3 | Wails v2 (never in v3 code) |
|---|---|---|
| Entry point | application.New(application.Options{...}), then app.Run() | wails.Run(&options.App{...}) |
| Exposing Go | Services: []application.Service{application.NewService(&T{})} | Bind: []any{&T{}} |
| Lifecycle | ServiceStartup(ctx, application.ServiceOptions) error and ServiceShutdown() error on the service; Options.OnShutdown | OnStartup, OnDomReady, OnShutdown, OnBeforeClose in options.App |
| Runtime calls | app.Event.Emit, app.Dialog.SaveFile(), app.Window.NewWithOptions | runtime.EventsEmit(ctx, ...), runtime.SaveFileDialog(ctx, ...) |
| Frontend | frontend/bindings/<import path>/ and @wailsio/runtime | wailsjs/go/... and window.go |
| Tooling | wails3 CLI, Taskfile.yml, build/config.yml | wails CLI, wails.json |
| Linux | gtk4 and webkitgtk-6.0; -tags gtk3 for GTK3 | gtk+-3.0 and webkit2gtk-4.0 or -4.1 |
Imports from github.com/wailsapp/wails/v2/..., a runtime. call that
takes a context, or a wailsjs path in a v3 project is a mixing mistake.
The service contract
Keep each service thin, its exported methods the whole frontend API, and everything native behind an interface the tests can replace:
// examples/wails3/notes/service.go (trimmed: storage and the other methods omitted)
type Native interface {
SaveFile(defaultName string) (string, error) // "" when cancelled
Emit(event string, data any)
}
type Service struct {
mu sync.Mutex // bound calls can run concurrently
notes []Note
native Native
}
func NewService(native Native) *Service { return &Service{native: native} }
func (s *Service) SaveNote(in NoteInput) (Note, error) {
in, err := validate(in)
if err != nil {
return Note{}, err // rejects the frontend promise
}
return s.store(Note(in)) // locks s.mu and emits EventNotesChanged
}
The app wires it up in main:
// examples/wails3/main.go (trimmed: init, window size, Mac options, Emit, and the file filter omitted)
// assets is the //go:embed all:frontend/dist filesystem (see Assets below).
func main() {
app := application.New(application.Options{
Name: "Notes",
Assets: application.AssetOptions{Handler: application.AssetFileServerFS(assets)},
})
app.RegisterService(application.NewService(notes.NewService(desktop{app})))
app.Window.NewWithOptions(application.WebviewWindowOptions{Title: "Notes", URL: "/"})
if err := app.Run(); err != nil {
log.Fatal(err)
}
}
// desktop implements notes.Native; the service's tests use a fake instead.
type desktop struct{ app *application.App }
func (d desktop) SaveFile(name string) (string, error) {
return d.app.Dialog.SaveFile().SetFilename(name).PromptForSingleSelection()
}
Both blocks are trimmed from complete files that build and pass their tests:
examples/wails3/main.go
and
examples/wails3/notes/service.go.
Copy those for a runnable starting point; the desktop build needs cgo (see
references/building.md).
application.NewServicetakes a pointer to a named, non-generic struct. Register one instance per type, inOptions.Servicesor withapp.RegisterServicebeforeRun. A service registered afterRunstarts is dropped and the error goes to `Options.