Creating Custom Templates

This guide will walk you through the process of creating a custom template for Wails v3.

Why would I make a custom template?

Wails comes with a number of pre-configured templates that allow you to get your application up and running quickly. But if you need a more customised setup, you can create your own template to suit your needs. This can then be shared with the Wails community for others to use.

1. Generating a Template

To create a custom template, you can use the wails generate template command:

wails3 generate template -name mytemplate

This will create a new directory called “mytemplate” in your current directory.

The wails3 generate template command supports the following options:

Option	Description	Default
-name	The name of your template (required)	-
-frontend	Path to an existing frontend directory to include	-
-author	The author of the template	-
-description	A description of the template	-
-helpurl	URL for template documentation	-
-dir	Directory to generate the template in	Current directory
-version	Template version	v0.0.1

For example, to create a template with all options:

wails3 generate template \
  -name "My Custom Template" \
  -frontend ./my-existing-frontend \
  -author "Your Name" \
  -description "A template with my preferred setup" \
  -helpurl "https://github.com/yourusername/template-docs" \
  -dir ./templates \
  -version "v1.0.0"

Tip

Using the -frontend option will copy an existing web frontend project into the template.

2. Configure Template Metadata

If you didn’t specify the template configuration when generating the template, you can update the template.json file in the template directory:

{
  "name": "Your Template Name",          // Display name of your template
  "shortname": "template-shortname",     // Used when referencing your template
  "author": "Your Name",                 // Template author
  "description": "Template description", // Template description
  "helpurl": "https://your-docs.com",    // Documentation URL
  "version": "v0.0.1",                   // Template version
  "schema": 3                            // Must be kept as 3 for Wails v3
}

Caution

The schema field must remain set to 3 for compatibility with Wails v3.

3. Set Up Build Tasks

In the build directory is Taskfile.yml where you can define your template’s build process. This file uses Task for build automation. The key steps are:

tasks:
  install:frontend:deps:
    summary: Install frontend dependencies
    dir: frontend
    sources:
      - package.json
      - package-lock.json
    generates:
      - node_modules/*
    preconditions:
      - sh: npm version
        msg: "Looks like npm isn't installed. Npm is part of the Node installer: https://nodejs.org/en/download/"
    cmds:
      - npm install

  build:frontend:
    summary: Build the frontend project
    dir: frontend
    sources:
      - "**/*"
    generates:
      - dist/*
    deps:
      - task: install:frontend:deps
      - task: generate:bindings
    cmds:
      - npm run build -q

4. Frontend Setup

If you did not use -frontend when generating the template, you need to add frontend files to your template.

There are a number of ways to set up your frontend: starting from scratch or using an existing framework.

Start from Scratch

If you want to start from scratch, you can create your frontend project just like you would for any web application. The frontend directory in your template is just a regular directory where you can set up your preferred development environment. You might want to use build tools like Vite, webpack, or even just plain HTML, CSS, and JavaScript - it’s entirely up to you!

For example, if you’re using Vite, you could navigate to the frontend directory and run:

npm create vite@latest .

Then follow the prompts to set up your project exactly how you want it. The key thing to remember is that this is just a regular frontend project - you can use any tools, frameworks, or libraries you’re familiar with.

Use Existing Framework

For this example, we’ll use Vite to set up a React frontend project:

npm create vite@latest frontend -- --template react
cd frontend
npm install

Now you have the frontend files in place, update common/Taskfile.yml with the appropriate commands:

tasks:
   install:frontend:deps:
     summary: Install frontend dependencies
     dir: frontend
     sources:
       - package.json
       - package-lock.json
     generates:
       - node_modules/*
     preconditions:
       - sh: npm version
         msg: "Looks like npm isn't installed. Npm is part of the Node installer: https://nodejs.org/en/download/"
     cmds:
       - npm install

   build:frontend:
     summary: Build the frontend project
     dir: frontend
     sources:
       - "**/*"
     generates:
       - dist/*
     deps:
       - task: install:frontend:deps
       - task: generate:bindings
     cmds:
       - npm run build -q

Note

For this example, the default Tasks do not need updating as they use the standard npm install and npm run build commands.

5. Configure the Go Application

The default files in the template directory are sufficient to get users started. However, you may want to provide some additional functionality to demonstrate your template’s capabilities. The best way to do this is to rename main.go.tmpl to main.go and edit it like any other Go file. Once finished, ensure you rename it back to main.go.tmpl before committing your changes. If you do not care about having a templated main.go file (the default template injests the project name into the Name field of the application), you can skip this step.

Template Variables

Wails uses Go’s templating engine to process files with the .tmpl extension. During template generation, several variables are available for use in your template files:

Variable	Description	Example
Name	The name of the project	"MyApp"
BinaryName	The name of the generated binary	"myapp"
ProductName	The product name	"My Application"
ProductDescription	Description of the product	"An awesome application"
ProductVersion	Version of the product	"1.0.0"
ProductCompany	Company name	"My Company Ltd"
ProductCopyright	Copyright information	"Copyright 2024 My Company Ltd"
ProductComments	Additional product comments	"Built with Wails"
ProductIdentifier	Unique product identifier	"com.mycompany.myapp"
Typescript	Whether TypeScript is being used	true or false
WailsVersion	The version of Wails being used	"3.0.0"

You can use these variables in your template files using Go’s template syntax:

main.go.tmpl

package main

import (
    "github.com/wailsapp/wails/v3/pkg/application"
)

func main() {
    app := application.New(application.Options{
        Name:        "{{.ProductName}}",
        Description: "{{.ProductDescription}}",
    })
    // ...
}

Tip

Templating can be applied to any file in your template, even html files, so long as the filename has .tmpl in its name.

6. Testing Your Template

To test your template:

1. Generate a project using your template: wails3 init -n testproject -t path/to/your/template
2. Run wails3 build to generate the production build and make sure the binary in bin runs correctly
3. Run wails3 dev to start the development server.
4. Test that changes to the frontend code are reflected in the application.
5. Test that changes to the Go code rebuild and relaunch the application

7. Sharing Your Template

Once your template is ready, you can share it with the community by hosting it on GitHub. Here’s how:

1. Create a new GitHub repository for your template
2. Push your template code to the repository
3. Tag your releases using semantic versioning (e.g., v1.0.0)

Users can then use your template directly from GitHub using the HTTPS URL:

wails3 init -n myapp -t https://github.com/yourusername/your-template

You can also specify a particular version using the URL format:

# Use a specific version tag
wails3 init -n myapp -t https://github.com/yourusername/your-template/releases/tag/v1.0.0

# Use a specific branch
wails3 init -n myapp -t https://github.com/yourusername/your-template/tree/main

To test your template before sharing:

1. Push your changes to GitHub

2. Create a new test project using the HTTPS URL:

   wails3 init -n testapp -t https://github.com/yourusername/your-template

3. Verify that all files are correctly generated

4. Test the build and development workflow as described in the testing section

   Note

   Make sure your repository is public if you want others to use your template.

For more information, visit the Wails documentation

Best Practices

Let’s talk about some key practices that will help make your template more useful and maintainable. Here are the main areas to focus on:

1. Make Your Template Easy to Understand

   • Write a clear, helpful README.md that gets users started quickly
   • Add comments in your config files to explain the “why” behind your choices
   • Show examples of common customisations - users love to see real-world use cases!

2. Keep Dependencies Happy

   • Stay on top of your frontend package updates
   • Lock down specific versions in package.json to avoid surprises
   • Let users know upfront what they’ll need to have installed

3. Love Your Template

   • Keep it fresh with regular updates
   • Give it a thorough test drive before sharing
   • Share it with the Wails community - we’d love to see what you create!