wails/mkdocs-website/docs/en/development/introduction.md

Introduction

!!! note This guide is a work in progress.

Thanks for wanting to help out with development of Wails! This guide will help you get started.

Getting Started

• Git clone this repository. Checkout the v3-alpha branch.

• Install the CLI: cd v3/cmd/wails3 && go install

• Optional: If you are wanting to use the build system to build frontend code, you will need to install npm.

Building

For simple programs, you can use the standard go build command. It's also possible to use go run.

Wails also comes with a build system that can be used to build more complex projects. It utilises the awesome Task build system. For more information, check out the task homepage or run wails task --help.

Project layout

The project has the following structure:

```
v3
├── cmd/wails3                  // CLI
├── examples                   // Examples of Wails apps
├── internal                   // Internal packages
|   ├── runtime                // The Wails JS runtime
|   └── templates              // The supported project templates
├── pkg
|   ├── application            // The core Wails library
|   └── events                 // The event definitions
|   └── mac                    // macOS specific code used by plugins
|   └── w32                    // Windows specific code
├── plugins                    // Supported plugins
├── tasks                      // General tasks
└── Taskfile.yaml              // Development tasks configuration
```

Development

Alpha Todo List

We are currently tracking known issues and tasks in the Alpha Todo List. If you want to help out, please check this list and follow the instructions in the Feedback page.

Adding window functionality

The preferred way to add window functionality is to add a new function to the pkg/application/webview_window.go file. This should implement all the functionality required for all platforms. Any platform specific code should be called via a webviewWindowImpl interface method. This interface is implemented by each of the target platforms to provide the platform specific functionality. In some cases, this may do nothing. Once you've added the interface method, ensure each platform implements it. A good example of this is the SetMinSize method.

• Mac: webview_window_darwin.go
• Windows: webview_window_windows.go
• Linux: webview_window_linux.go

Most, if not all, of the platform specific code should be run on the main thread. To simplify this, there are a number of invokeSync methods defined in application.go.

Updating the runtime

The runtime is located in v3/internal/runtime. When the runtime is updated, the following steps need to be taken:

wails3 task runtime:build

Events

Events are defined in v3/pkg/events. When adding a new event, the following steps need to be taken:

• Add the event to the events.txt file
• Run wails3 task events:generate

There are a number of types of events: platform specific application and window events + common events. The common events are useful for cross-platform event handling, but you aren't limited to the "lowest common denominator". You can use the platform specific events if you need to.

When adding a common event, ensure that the platform specific events are mapped. An example of this is in window_webview_darwin.go:

		// Translate ShouldClose to common WindowClosing event
		w.parent.On(events.Mac.WindowShouldClose, func(_ *WindowEventContext) {
			w.parent.emit(events.Common.WindowClosing)
		})

NOTE: We may try to automate this in the future by adding the mapping to the event definition.

Plugins

Plugins are a way to extend the functionality of your Wails application.

Creating a plugin

Plugins are standard Go structure that adhere to the following interface:

type Plugin interface {
    Name() string
    Init(*application.App) error
    Shutdown()
    CallableByJS() []string
    InjectJS() string
}

The Name() method returns the name of the plugin. This is used for logging purposes.

The Init(*application.App) error method is called when the plugin is loaded. The *application.App parameter is the application that the plugin is being loaded into. Any errors will prevent the application from starting.

The Shutdown() method is called when the application is shutting down.

The CallableByJS() method returns a list of exported functions that can be called from the frontend. These method names must exactly match the names of the methods exported by the plugin.

The InjectJS() method returns JavaScript that should be injected into all windows as they are created. This is useful for adding custom JavaScript functions that complement the plugin.

The built-in plugins can be found in the v3/plugins directory. Check them out for inspiration.

Tasks

The Wails CLI uses the Task build system. It is imported as a library and used to run the tasks defined in Taskfile.yaml. The main interfacing with Task happens in v3/internal/commands/task.go.

Upgrading Taskfile

To check if there's an upgrade for Taskfile, run wails3 task -version and check against the Task website.

To upgrade the version of Taskfile used, run:

wails3 task taskfile:upgrade

If there are incompatibilities then they should appear in the v3/internal/commands/task.go file.

Usually the best way to fix incompatibilities is to clone the task repo at https://github.com/go-task/task and look at the git history to determine what has changed and why.

To check all changes have worked correctly, re-install the CLI and check the version again:

wails3 task cli:install
wails3 task -version

Opening a PR

Make sure that all PRs have a ticket associated with them providing context to the change. If there is no ticket, please create one first. Ensure that all PRs have updated the CHANGELOG.md file with the changes made. The CHANGELOG.md file is located in the mkdocs-website/docs directory.

Misc Tasks

Upgrading Taskfile

The Wails CLI uses the Task build system. It is imported as a library and used to run the tasks defined in Taskfile.yaml. The main interfacing with Task happens in v3/internal/commands/task.go.

To check if there's an upgrade for Taskfile, run wails3 task -version and check against the Task website.

To upgrade the version of Taskfile used, run:

wails3 task taskfile:upgrade

If there are incompatibilities then they should appear in the v3/internal/commands/task.go file.

Usually the best way to fix incompatibilities is to clone the task repo at https://github.com/go-task/task and look at the git history to determine what has changed and why.

To check all changes have worked correctly, re-install the CLI and check the version again:

wails3 task cli:install
wails3 task -version