Which strategy should I use for Wails v3 WebView Runtime and Plugin?
Desktop app teams using Wails need change-awareness on v3 runtime and plugin breaks to judge whether to migrate now or stay on older releases while packaging stabilizes.
Blockers
- Recent v3 changes include Manager API refactoring/reorganization.
- Recent v3 changes include event API changes.
- Runtime initialization requires importing @wailsio/runtime for side effects or using a generated runtime bundle.
- Windows still depends on WebView2 being installed.
- Linux still depends on webkit2gtk.
- The official v2-to-v3 migration guide describes coordinated breaking changes across initialization, bindings, runtime calls, event handling, generated imports, and wails.json structure.
Who this is for
- small-team
- low-ops
Candidates
Migrate to Wails v3 now if you need the new runtime and service/plugin model
Wails v3 is a complete rewrite, and the official v2-to-v3 migration guide estimates "1-4 hours for typical applications". As of 2026-04-01, the official release track is still alpha/pre-release, and the GitHub releases page warns that v3 alpha builds may contain bugs or incomplete features. The migration is not a patch upgrade: application startup moves away from a single `wails.Run()` call, backend bindings move from context-coupled structs to services, and frontend runtime usage moves to `@wailsio/runtime` or a generated runtime bundle. v3 also expands services to provide plugin functionality, adds a Vite plugin for typed events, and documents stable vs unstable API areas before final release.
When to choose
Use this when you need v3-specific architecture benefits now, especially service-based bindings, typed event workflows, multi-window patterns, or plugin-oriented extension points. The decisive factor is whether your team can tolerate alpha churn and do active migration testing across packaging targets.
Tradeoffs
You get the cleaner object-oriented runtime, improved service model, and newer frontend/runtime tooling, but you accept pre-release risk and repeated refactor work as the alpha line changes.
Cautions
The breaking surface is real: recent v3 changes include Manager API refactoring, event API changes, JS/TS binding type changes, renamed or removed window APIs, and runtime initialization requirements such as `import "@wailsio/runtime"` for side effects. Windows still depends on WebView2 being installed, Linux still depends on `gcc`, `gtk3`, and `webkit2gtk`, and GTK4/WebKitGTK 6 support is still marked experimental behind `-tags gtk4`. No official pricing number was surfaced in the official docs searched as of 2026-04-01; check official project pages if commercial support matters.
Stay on Wails v2 for production and track v3 until packaging and APIs settle
As of 2026-04-01, Wails v3 has not yet reached a final stable release in the official channels searched, while the main `wails.io` site still presents Wails v2 as the production-facing experience. The official migration guide shows that moving from v2 to v3 requires coordinated changes to application initialization, bindings, runtime calls, event handling, generated frontend binding imports, and `wails.json` structure. The v3 changelog also shows ongoing blocker-level breaks, including Manager API reorganization, event API changes, optional map keys in generated JS/TS bindings, and packaging/runtime adjustments. If your main concern is shipping and maintaining packaged desktop builds with low churn, staying on v2 is the lower-risk choice.
When to choose
Use this when you are production-first, packaging stability matters more than architecture cleanup, or your team cannot absorb repeated migration work in the next release cycle. The decisive factor is whether you need v3-only capabilities badly enough to justify alpha volatility.
Tradeoffs
You avoid immediate rewrite cost and alpha regressions, but you delay access to the v3 service/plugin model, newer runtime package conventions, and newer window/event architecture.
Cautions
Do not treat the eventual v2-to-v3 move as trivial technical debt: the official guide documents a broad migration, not a one-line version bump. If you stay on v2, keep watching the v3 changelog and releases so you do not get surprised by final-release migration requirements or packaging workflow changes later. No official pricing number was surfaced in the official docs searched as of 2026-04-01; check official project pages if commercial support matters.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Which strategy should I use for Wails v3 WebView Runtime and Plugin?"