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:
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.
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:
app := wails.CreateApp(/* options */)
app.Bind(basic)
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:
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:
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.
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 JavaScriptCSS
- 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
:
//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. |