Migrating from v2 to v3

Wails v3 is a complete rewrite with significant improvements in architecture, performance, and developer experience. This guide helps you migrate your v2 application to v3.

Key changes:

• New application structure
• Improved bindings system
• Enhanced window management
• Better event system
• Simplified configuration

Migration time: 1-4 hours for typical applications

Automated Migration

Experimental

The wails3 migrate command is included in the V3 CLI, but it is experimental. It handles common project shapes well, but your mileage may vary: review the generated code and test your application thoroughly. If it stumbles on your project, please open an issue with the details so we can improve it. Pull requests are very welcome.

The CLI can perform most of this guide for you:

wails3 migrate -d ./myv2project -o ./myv3project

The command migrates what maps deterministically and documents the rest. It does not rewrite your application logic and it does not generate compatibility layers: code that still uses the v2 API is left untouched, and every such location is listed in a generated MIGRATION.md with its concrete v3 replacement, so the remaining work is a clear checklist rather than a half-migrated codebase.

What it migrates for you:

• main.go is rewritten around application.New() + app.Window.NewWithOptions(), keeping your own code and comments intact. Options are mapped to their v3 equivalents, including platform-specific window options.
• Structs listed in Bind become v3 services, and the OnStartup/OnDomReady/OnShutdown/OnBeforeClose callbacks are wired to their v3 counterparts (application events, OnShutdown, ShouldQuit).
• wails.json is replaced by the v3 project files: a Taskfile-based build system and build/config.yml populated from your v2 metadata (product info, file associations, protocols).
• go.mod swaps wails/v2 for wails/v3; everything else is preserved.
• The frontend is copied over and @wailsio/runtime is added to its dependencies. The generated wailsjs/ directory is not carried over - it is v2 build output that cannot work with v3.

What it documents for you (in MIGRATION.md):

• Every call into the v2 runtime package, listed by file and line with the v3 replacement (for example runtime.EventsEmit(ctx, ...) becomes app.Event.Emit(...)). The project intentionally does not compile until these are ported - the compiler points at exactly the listed locations.
• Every frontend import of wailsjs/runtime or wailsjs/go/..., with the @wailsio/runtime equivalent and the wails3 generate bindings workflow for bindings.
• Options that need a human decision (menus, custom loggers, EnumBind, …), each with instructions.

The rest of this guide explains the underlying changes in depth - use it together with the generated checklist.

Breaking Changes

Application Initialisation

In v2, application setup, window configuration, and execution were all combined into a single wails.Run() call. This monolithic approach made it difficult to create multiple windows, handle errors at different stages, or test individual components of your application.

v3 separates these concerns into distinct phases: application creation, window creation, and execution. This separation gives you explicit control over each stage of your application’s lifecycle and makes the code more modular and testable.

v2:

err := wails.Run(&options.App{
    Title:  "My App",
    Width:  1024,
    Height: 768,
    Bind: []interface{}{
        &GreetService{},
    },
})

v3:

app := application.New(application.Options{
    Name: "My App",
    Services: []application.Service{
        application.NewService(&GreetService{}),
    },
})

window := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:  "My App",
    Width:  1024,
    Height: 768,
})

app.Run()

Why this is better:

• Multi-window support: You can create windows dynamically at any point, not just at startup
• Better error handling: Each phase can be validated separately with proper error handling
• Clearer code: The separation makes it obvious what’s happening at each stage
• More testable: You can test application setup without running the event loop
• More flexible: Windows can be created, destroyed, and recreated throughout the application lifecycle

Bindings

In v2, every bound struct required a context field and a startup(ctx) method to receive the runtime context. This created tight coupling between your business logic and the Wails runtime, making code harder to test and understand.

v3 introduces the service pattern, where your structs are completely standalone and don’t need to store runtime context. If a service needs access to the application instance, it explicitly receives it through dependency injection rather than implicit context threading.

v2:

type App struct {
    ctx context.Context
}

func (a *App) startup(ctx context.Context) {
    a.ctx = ctx
}

func (a *App) Greet(name string) string {
    return "Hello " + name
}

v3:

type GreetService struct{}

func (g *GreetService) Greet(name string) string {
    return "Hello " + name
}

// Register as service
app := application.New(application.Options{
    Services: []application.Service{
        application.NewService(&GreetService{}),
    },
})

Why this is better:

• No implicit dependencies: Services are plain Go structs without hidden runtime dependencies
• Easier testing: You can test service methods without mocking a Wails context
• Clearer code: Dependencies are explicit (passed as constructor arguments) rather than hidden in a context field
• Better organization: Services can be grouped by domain rather than all living in a single App struct
• Proper initialization: Use ServiceStartup() method when you need initialization, making it explicit

Runtime

In v2, all runtime operations required passing a context to global functions from the runtime package. This created tight coupling to the context object throughout your codebase and made the API feel procedural rather than object-oriented.

v3 replaces the context-based runtime with direct method calls on application and window objects. Operations are called directly on the objects they affect, making the code more intuitive and object-oriented.

v2:

import "github.com/wailsapp/wails/v2/pkg/runtime"

runtime.WindowSetTitle(a.ctx, "New Title")
runtime.EventsEmit(a.ctx, "event-name", data)

v3:

// Store app reference
type MyService struct {
    app *application.App
}

func (s *MyService) UpdateTitle() {
    window := s.app.Window.Current()
    window.SetTitle("New Title")
}

func (s *MyService) EmitEvent() {
    s.app.Event.Emit("event-name", data)
}

Why this is better:

• Object-oriented design: Methods are called on the objects they affect (window, app, menu, etc.)
• Clearer intent: window.SetTitle() is more obvious than runtime.WindowSetTitle(ctx, ...)
• Better IDE support: Autocomplete works properly when methods are on objects
• Multi-window clarity: With multiple windows, you explicitly choose which window to operate on
• No context threading: You don’t need to pass context through every function

Frontend Bindings

In v2, bindings were organized by Go package and struct name, typically resulting in paths like wailsjs/go/main/App. This structure didn’t reflect logical grouping and made it hard to find related functionality.

v3 organizes bindings by service name and application module, creating a clearer logical structure. The bindings are generated into a bindings directory organized by your application name and service names, making it easier to understand what functionality is available.

v2:

import { Greet } from '../wailsjs/go/main/App'

const result = await Greet("World")

v3:

import { Greet } from './bindings/changeme/greetservice'

const result = await Greet("World")

Why this is better:

• Logical organization: Bindings are grouped by service name rather than Go package structure
• Clearer imports: The path reflects the domain logic (greetservice) not the file structure (main/App)
• Better discoverability: You can navigate bindings by feature rather than by technical structure
• Consistent naming: Service-based organization matches your backend architecture
• Simpler paths: No more ../wailsjs/go prefix - just ./bindings

Events

In v2, events used variadic interface{} parameters and required passing context to every event function. Event handlers received untyped data that needed manual type assertions, making the event system error-prone and hard to debug.

v3 introduces typed event objects and removes the context requirement. Event handlers receive a proper event object with typed data, making the event system more reliable and easier to use.

v2:

runtime.EventsOn(ctx, "event-name", func(data ...interface{}) {
    // Handle event
})

runtime.EventsEmit(ctx, "event-name", data)

v3:

app.Event.On("event-name", func(e *application.CustomEvent) {
    data := e.Data
    // Handle event
})

app.Event.Emit("event-name", data)

Why this is better:

• Type safety: Events use proper event objects instead of ...interface{}
• Better debugging: Event objects contain metadata like event name, making debugging easier
• Clearer API: app.Event.On() and app.Event.Emit() are more intuitive than runtime functions
• No context needed: Events work directly on the app object without threading context
• Simpler handlers: Event handlers have a clear signature instead of variadic parameters

Windows

v2 supported only a single window per application. The window was created at startup and all window operations were performed through runtime functions that implicitly targeted that single window.

v3 introduces native multi-window support as a core feature. Each window is a first-class object with its own methods and lifecycle. You can create, manage, and destroy multiple windows dynamically throughout your application’s lifetime.

v2:

// Single window only
runtime.WindowSetSize(ctx, 800, 600)

v3:

// Multiple windows supported
window1 := app.Window.New()
window1.SetSize(800, 600)

window2 := app.Window.New()
window2.SetSize(1024, 768)

Why this is better:

• Multi-window applications: Build apps with multiple independent windows (dashboards, preferences, tools, etc.)
• Explicit window references: Each window is an object you can store and manipulate directly
• Dynamic window creation: Create and destroy windows at any time during runtime
• Independent window state: Each window has its own events, properties, and lifecycle
• Better architecture: Window management is object-oriented rather than context-based

Migration Steps

Step 1: Update Dependencies

go.mod:

module myapp

go 1.25.0

require (
    github.com/wailsapp/wails/v3 v3.0.0-beta.0
)

Update:

go get github.com/wailsapp/wails/v3@latest
go mod tidy

Step 2: Update main.go

v2:

package main

import (
    "embed"
    "github.com/wailsapp/wails/v2/pkg/options"
    "github.com/wailsapp/wails/v2/pkg/options/assetserver"
    "github.com/wailsapp/wails/v2/pkg/options/windows"
)

//go:embed all:frontend/dist
var assets embed.FS

func main() {
    app := NewApp()

    err := wails.Run(&options.App{
        Title:  "My App",
        Width:  1024,
        Height: 768,
        AssetServer: &assetserver.Options{
            Assets: assets,
        },
        Bind: []interface{}{
            app,
        },
        Windows: &windows.Options{
            WebviewIsTransparent: false,
        },
    })

    if err != nil {
        println("Error:", err.Error())
    }
}

v3:

package main

import (
    "embed"
    "github.com/wailsapp/wails/v3/pkg/application"
)

//go:embed frontend/dist
var assets embed.FS

func main() {
    app := application.New(application.Options{
        Name: "My App",
        Services: []application.Service{
            application.NewService(&MyService{}),
        },
        Assets: application.AssetOptions{
            Handler: application.AssetFileServerFS(assets),
        },
    })

    app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title:  "My App",
        Width:  1024,
        Height: 768,
    })

    err := app.Run()
    if err != nil {
        panic(err)
    }
}

Step 3: Convert App Struct to Service

v2:

type App struct {
    ctx context.Context
}

func NewApp() *App {
    return &App{}
}

func (a *App) startup(ctx context.Context) {
    a.ctx = ctx
    // Initialisation
}

func (a *App) Greet(name string) string {
    return "Hello " + name
}

v3:

type MyService struct {
    app *application.App
}

func NewMyService(app *application.App) *MyService {
    return &MyService{app: app}
}

func (s *MyService) ServiceStartup(ctx context.Context, options application.ServiceOptions) error {
    // Initialisation
    return nil
}

func (s *MyService) Greet(name string) string {
    return "Hello " + name
}

// Register after app creation
app := application.New(application.Options{})
app.RegisterService(application.NewService(NewMyService(app)))

Step 4: Update Runtime Calls

v2:

func (a *App) DoSomething() {
    runtime.WindowSetTitle(a.ctx, "New Title")
    runtime.EventsEmit(a.ctx, "update", data)
    runtime.LogInfo(a.ctx, "Message")
}

v3:

func (s *MyService) DoSomething() {
    window := s.app.Window.Current()
    window.SetTitle("New Title")

    s.app.Event.Emit("update", data)

    s.app.Logger.Info("Message")
}

Step 5: Update Frontend

Generate new bindings:

wails3 generate bindings

Update imports:

// v2
import { Greet } from '../wailsjs/go/main/App'

// v3
import { Greet } from './bindings/changeme/myservice'

Update event handling:

// v2
import { EventsOn, EventsEmit } from '../wailsjs/runtime/runtime'

EventsOn("update", (data) => {
    console.log(data)
})

EventsEmit("action", data)

// v3
import { Events } from '@wailsio/runtime'

Events.On("update", (data) => {
    console.log(data)
})

Events.Emit("action", data)

Step 6: Update Configuration

v2 (wails.json):

{
  "name": "myapp",
  "outputfilename": "myapp",
  "frontend:install": "npm install",
  "frontend:build": "npm run build",
  "frontend:dev:watcher": "npm run dev",
  "frontend:dev:serverUrl": "auto"
}

v3 (build/config.yml):

version: '3'

info:
  productName: "myapp"
  productIdentifier: "com.example.myapp"

dev_mode:
  root_path: .

V3 project-level development and build commands are defined in the root Taskfile.yml. The generated project keeps frontend commands there and uses build/config.yml for application and packaging configuration. Do not create a V3 wails.json by copying the V2 file.

Feature Mapping

dialogs

v2:

selection, err := runtime.OpenFileDialog(ctx, runtime.OpenDialogOptions{
    Title: "Select File",
})

v3:

selection, err := app.Dialog.OpenFileWithOptions(&application.OpenFileDialogOptions{
    Title: "Select File",
}).PromptForSingleSelection()

Menus

v2:

menu := menu.NewMenu()
menu.Append(menu.Text("File", nil, []*menu.MenuItem{
    menu.Text("Quit", nil, func(_ *menu.CallbackData) {
        runtime.Quit(ctx)
    }),
}))

v3:

menu := app.NewMenu()
fileMenu := menu.AddSubmenu("File")
fileMenu.Add("Quit").OnClick(func(ctx *application.Context) {
    app.Quit()
})

System Tray

v2:

// Not available in v2

v3:

systray := app.SystemTray.New()
systray.SetIcon(iconBytes)
systray.SetLabel("My App")

menu := app.NewMenu()
menu.Add("Show").OnClick(showWindow)
menu.Add("Quit").OnClick(app.Quit)
systray.SetMenu(menu)

Common Issues

Issue: Bindings not found

Problem: Import errors after migration

Solution:

# Regenerate bindings
wails3 generate bindings

# Check output directory
ls frontend/bindings

Issue: Context errors

Problem: ctx not available

Solution:

Store app reference instead:

type MyService struct {
    app *application.App
}

func NewMyService(app *application.App) *MyService {
    return &MyService{app: app}
}

Issue: Window methods not working

Problem: runtime.WindowSetTitle() doesn’t exist

Solution:

Use window methods directly:

window := s.app.Window.Current()
window.SetTitle("New Title")

Issue: Events not firing

Problem: Events registered but not received

Solution:

Check event names match exactly:

// Go
app.Event.Emit("my-event", data)

// JavaScript
OnEvent("my-event", handler)  // Must match exactly

Testing Migration

Checklist

• Application starts without errors
• All bindings work
• Events are sent and received
• Windows open and close correctly
• Menus work (if applicable)
• dialogs work (if applicable)
• System tray works (if applicable)
• Build process works
• Production build works

Test Commands

# Development
wails3 dev

# Build
wails3 build

# Generate bindings
wails3 generate bindings

Benefits of v3

Performance

• Faster startup - Optimised initialisation
• Lower memory - Efficient resource usage
• Better bridge - <1ms call overhead

Features

• Multi-window - Native support
• System tray - Built-in
• Better events - Typed, simpler API
• Services - Better code organisation

Developer Experience

• Type safety - Full TypeScript support
• Better errors - Clear error messages
• Hot reload - Faster development
• Better docs - Comprehensive guides

Getting Help

Reporting migration problems

Migration tool failures are bugs. Before opening an issue, reduce the problem to the smallest reproducible V2 project you can and include:

• the Wails V2 version and the V3 CLI version or commit;
• the operating system and architecture;
• the exact wails3 migrate command;
• the command output and generated MIGRATION.md;
• wails3 doctor output; and
• a redacted project or minimal reproduction, if the project contains private code.

Open the report in the Wails issue tracker using the bug report template. Do not attach secrets, signing credentials, or private source code.

If you want to propose a change to the migration behavior or V3 API, submit a Wails Enhancement Proposal as a pull request. Product proposals should not be filed as ordinary feature requests.

Resources

• Documentation
• Discord Community
• GitHub Issues
• Examples

Common Questions

Q: Can I run v2 and v3 side by side?
A: Yes, they use different import paths.

Q: Is v3 production-ready?
A: v3 is beta software with a stable desktop API. Applications are running in production with it, but test thoroughly before deployment. v2 remains the current stable release.

Q: Will v2 be maintained?
A: Yes, v2 will receive critical updates.

Q: How long does migration take?
A: 1-4 hours for typical applications.

Next Steps

Quick Start

Get started with Wails v3.

Learn More →

Core Concepts

Understand v3 architecture.

Learn More →

Bindings

Learn the new bindings system.

Learn More →

Examples

See complete v3 examples.

View Examples →

---

Questions? Ask in Discord or open an issue.