
# 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](/docs/reference/options#application-options).

```go title="v2"
	err := wails.Run(&options.App{
		Title:  "MyApp",
		Width:  800,
		Height: 600,
		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](/docs/reference/options#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](/docs/reference/options#application-options):

- [OnStartup](/docs/reference/options#onstartup)
- [OnShutdown](/docs/reference/options#onshutdown)
- [OnDomReady](/docs/reference/options#ondomready)

Note: [OnDomReady](/docs/reference/options#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](/docs/reference/runtime/intro).

In v1, the [runtime](/docs/reference/runtime/intro) 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](/docs/reference/options#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 frontend/dist
var assets embed.FS

func main() {
	err := wails.Run(&options.App{
	    /* Other 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](/docs/reference/options#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>

