Skip to content

Wails v3 Build System#

Overview#

The Wails v3 build system is a flexible and powerful tool designed to streamline the build process for your Wails applications. It leverages Task, a task runner that allows you to define and run tasks easily. While the v3 build system is the default, Wails encourages a "bring your own tooling" approach, allowing developers to customize their build process as needed.

Learn more about how to use Task in the official documentation.

Task: The Heart of the Build System#

Task is a modern alternative to Make, written in Go. It uses a YAML file to define tasks and their dependencies. In the Wails v3 build system, Task plays a central role in orchestrating the build process.

The main Taskfile.yml is located in the project root, while platform-specific tasks are defined in build/Taskfile.<platform>.yml files.

Project Root
│
├── Taskfile.yml
│
└── build
    ├── Taskfile.windows.yml
    ├── Taskfile.darwin.yml
    ├── Taskfile.linux.yml
    └── Taskfile.common.yml

The Taskfile.common.yml file contains common tasks that are shared across platforms.

Taskfile.yml#

The Taskfile.yml file is the main entry point for the build system. It defines the tasks and their dependencies. Here's the default Taskfile.yml file:

version: '3'

includes:
  common: ./build/Taskfile.common.yml
  windows: ./build/Taskfile.windows.yml
  darwin: ./build/Taskfile.darwin.yml
  linux: ./build/Taskfile.linux.yml

vars:
  APP_NAME: "{{.ProjectName}}"
  BIN_DIR: "bin"
  VITE_PORT: '{{.WAILS_VITE_PORT | default 9245}}'

tasks:
  build:
    summary: Builds the application
    cmds:
      - task: "{{OS}}:build"

  package:
    summary: Packages a production build of the application
    cmds:
      - task: "{{OS}}:package"

  run:
    summary: Runs the application
    cmds:
      - task: "{{OS}}:run"

  dev:
    summary: Runs the application in development mode
    cmds:
      - wails3 dev -config ./build/devmode.config.yaml -port {{.VITE_PORT}}

  dev:reload:
    summary: Reloads the application
    cmds:
      - task: run

Platform-Specific Taskfiles#

Each platform has its own Taskfile, located in the build directory. These files define the core tasks for that platform. Each taskfile includes common tasks from the Taskfile.common.yml file.

Windows#

Location: build/Taskfile.windows.yml

The Windows-specific Taskfile includes tasks for building, packaging, and running the application on Windows. Key features include:

  • Building with optional production flags
  • Generating Windows .syso file
  • Creating an NSIS installer for packaging

Linux#

Location: build/Taskfile.linux.yml

The Linux-specific Taskfile includes tasks for building, packaging, and running the application on Linux. Key features include:

  • Building with optional production flags
  • Creating an AppImage for packaging
  • Generating .desktop file for Linux applications

macOS#

Location: build/Taskfile.darwin.yml

The macOS-specific Taskfile includes tasks for building, packaging, and running the application on macOS. Key features include:

  • Building with optional production flags
  • Creating an .app bundle for packaging
  • Setting macOS-specific build flags and environment variables

Wails3 Commands and Task Execution#

The wails3 task command is an embedded version of taskfile.dev, which executes the tasks defined in your Taskfile.yml.

The wails3 build and wails3 package commands are aliases for wails3 task build and wails3 task package respectively. When you run these commands, Wails internally translates them to the appropriate task execution:

  • wails3 build → wails3 task build
  • wails3 package → wails3 task package

Common Build Process#

Across all platforms, the build process typically includes the following steps:

  1. Tidying Go modules
  2. Building the frontend
  3. Generating icons
  4. Compiling the Go code with platform-specific flags
  5. Packaging the application (platform-specific)

Customising the Build Process#

While the v3 build system provides a solid default configuration, you can easily customise it to fit your project's needs. By modifying the Taskfile.yml and platform-specific Taskfiles, you can:

  • Add new tasks
  • Modify existing tasks
  • Change the order of task execution
  • Integrate with other tools and scripts

This flexibility allows you to tailor the build process to your specific requirements while still benefiting from the structure provided by the Wails v3 build system.

Development Mode#

The Wails v3 build system includes a powerful development mode that enhances the developer experience by providing live reloading and hot module replacement. This mode is activated using the wails3 dev command.

How It Works#

When you run wails3 dev, the following process occurs:

  1. The command checks for an available port, defaulting to 9245 if not specified.
  2. It sets up the environment variables for the frontend dev server (Vite).
  3. It starts the file watcher using the refresh library.

The refresh library is responsible for monitoring file changes and triggering rebuilds. It uses a configuration file, typically located at ./build/devmode.config.yaml, to determine which files to watch and what actions to take when changes are detected.

Configuration#

The development mode can be configured using the devmode.config.yaml file. Here's an example of its structure:

config:
  root_path: .
  log_level: warn
  debounce: 1000
  ignore:
    dir:
      - .git
      - node_modules
      - frontend
      - bin
    file:
      - .DS_Store
      - .gitignore
      - .gitkeep
    watched_extension:
      - "*.go"
    git_ignore: true
  executes:
    - cmd: wails3 task common:install:frontend:deps
      type: once
    - cmd: wails3 task common:dev:frontend
      type: background
    - cmd: go mod tidy
      type: blocking
    - cmd: wails3 task build
      type: blocking
    - cmd: wails3 task run
      type: primary

This configuration file allows you to:

  • Set the root path for file watching
  • Configure logging level
  • Set a debounce time for file change events
  • Ignore specific directories, files, or file extensions
  • Define commands to execute on file changes

Customising Development Mode#

You can customise the development mode experience by modifying the devmode.config.yaml file.

Some ways to customise include:

  1. Changing the watched directories or files
  2. Adjusting the debounce time to control how quickly the system responds to changes
  3. Adding or modifying the execute commands to fit your project's needs

You can also specify a custom configuration file and port:

wails3 dev -config ./path/to/custom/config.yaml -port 8080

Using a browser for development#

Whilst v2 fully supported the use of a browser for development, it caused a lot of confusion. Applications that would work in the browser would not necessarily work in the desktop application, as not all browser APIs are available in webviews.

For UI-focused development work, you still have the flexibility to use a browser in v3, by accessing the Vite URL at http://localhost:9245 in dev mode. This gives you access to powerful browser dev tools while working on styling and layout. When you're ready to test functionality like bindings and events, simply switch to the desktop view to ensure everything works perfectly in the production environment.