mirror of
https://github.com/wailsapp/wails.git
synced 2025-05-02 06:32:10 +08:00
192 lines
9.0 KiB
Plaintext
192 lines
9.0 KiB
Plaintext
# 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:
|
|
|
|
```go title="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](../reference/options.mdx#application-options).
|
|
|
|
```go title="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](../reference/options.mdx#application-options):
|
|
|
|
```go title="v1"
|
|
app := wails.CreateApp(/* options */)
|
|
app.Bind(basic)
|
|
```
|
|
|
|
```go title="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](../reference/options.mdx#application-options):
|
|
|
|
- [OnStartup](../reference/options.mdx#onstartup)
|
|
- [OnShutdown](../reference/options.mdx#onshutdown)
|
|
- [OnDomReady](../reference/options.mdx#ondomready)
|
|
|
|
Note: [OnDomReady](../reference/options.mdx#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:
|
|
|
|
```go title="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](../reference/runtime/intro.mdx).
|
|
|
|
In v1, the [runtime](../reference/runtime/intro.mdx) 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](../reference/options.mdx#onstartup) method.
|
|
|
|
```go title="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:
|
|
|
|
```shell
|
|
.
|
|
├── 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 title="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](../reference/options.mdx#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:
|
|
|
|
<p align="center">
|
|
|
|
| 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. |
|
|
|
|
</p>
|