Migrating from v1

Overview

Wails v2 is a significant change from v1. This document aims to highlight the changes and the steps in migrating an existing project.

Creating the Application

In v1, the main application is created using wails.CreateApp, bindings are added with app.Bind, then the application is run using app.Run().

Example:

v1

 app := wails.CreateApp(&wails.AppConfig{
    Title:  "MyApp",
    Width:  1024,
    Height: 768,
    JS:     js,
    CSS:    css,
    Colour: "#131313",
  })
  app.Bind(basic)
  app.Run()

In v2, there is just a single method, wails.Run(), that accepts application options.

v2

    err := wails.Run(&options.App{
        Title:  "MyApp",
        Width:  800,
        Height: 600,
        AssetServer: &assetserver.Options{
            Assets: assets,
        },
        Bind:   []interface{}{
            basic,
        },
    })

Binding

In v1, it was possible to bind both arbitrary functions and structs. In v2, this has been simplified to only binding structs. The struct instances that were previously passed to the Bind() method in v1, are now specified in the Bind field of the application options:

v1

  app := wails.CreateApp(/* options */)
  app.Bind(basic)

v2

    err := wails.Run(&options.App{
        /* other options */
        Bind: []interface{}{
            basic,
        },
    })

In v1, bound methods were available to the frontend at window.backend. This has changed to window.go.``

Application Lifecycle

In v1, there were 2 special methods in a bound struct: WailsInit() and WailsShutdown(). These have been replaced with 3 lifecycle hooks as part of the application options:

• OnStartup
• OnShutdown
• OnDomReady

Note: OnDomReady replaces the wails:ready system event in v1.

These methods can be standard functions, but a common practice is to have them part of a struct:

v2

    basic := NewBasicApp()
    err := wails.Run(&options.App{
        /* Other Options */
        OnStartup:  basic.startup,
        OnShutdown: basic.shutdown,
        OnDomReady: basic.domready,
    })
...
type Basic struct {
    ctx context.Context
}
func (b *Basic) startup(ctx context.Context) {
    b.ctx = ctx
}
...

Runtime

The runtime in v2 is much richer than v1 with support for menus, window manipulation and better dialogs. The signature of the methods has changed slightly - please refer the the Runtime Reference.

In v1, the runtime was available via a struct passed to WailsInit(). In v2, the runtime has been moved out to its own package. Each method in the runtime takes the context.Context that is passed to the OnStartup method.

Runtime Example

package main

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

type Basic struct {
    ctx context.Context
}

// startup is called at application startup
func (a *App) startup(ctx context.Context) {
    a.ctx = ctx
    runtime.LogInfo(ctx, "Application Startup called!")
}

Assets

The biggest change in v2 is how assets are handled.

In v1, assets were passed via 2 application options:

• JS - The application's JavaScript
• CSS - The application's CSS

This meant that the responsibility of generating a single JS and CSS file was on the developer. This essentially required the use of complicated packers such as webpack.

In v2, Wails makes no assumptions about your frontend assets, just like a webserver. All of your application assets are passed to the application options as an embed.FS.

This means there is no requirement to bundle your assets, encode images as Base64 or attempt the dark art of bundler configuration to use custom fonts.

At startup, Wails will scan the given embed.FS for index.html and use its location as the root path for all the other application assets - just like a webserver would.

Example: An application has the following project layout. All final assets are placed in the frontend/dist directory:

.
├── build/
├── frontend/
│   └── dist/
│       ├── index.html
│       ├── main.js
│       ├── main.css
│       └── logo.svg
├── main.go
└── wails.json

Those assets may be used by the application by simply creating an embed.FS:

Assets Example

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

func main() {
    err := wails.Run(&options.App{
        /* Other Options */
        AssetServer: &assetserver.Options{
            Assets: assets,
        },
    })
}

Of course, bundlers can be used if you wish to. The only requirement is to pass the final application assets directory to Wails using an embed.FS in the Assets key of the application options.

Project Configuration

In v1, the project configuration was stored in the project.json file in the project root. In v2, the project configuration is stored in the wails.json file in the project root.

The format of the file is slightly different. Here is a comparison:

v1	v2	Notes
name	name
description		Removed
author / name	author / name
author / email	author / email
version	version
binaryname	outputfilename	Changed
frontend / dir		Removed
frontend / install	frontend:install	Changed
frontend / build	frontend:build	Changed
frontend / bridge		Removed
frontend / serve		Removed
tags		Removed
	wailsjsdir	The directory to generate wailsjs modules
	assetdir	The directory of the compiled frontend assets for dev mode. This is normally inferred and could be left empty.
	reloaddirs	Comma separated list of additional directories to watch for changes and to trigger reloads in dev mode. This is only needed for some more advanced asset configurations.