Template Kustom

Wails ships with a set of built-in templates, but you can create your own and share them with the community. A custom template is just a Git repository — once it is hosted publicly, anyone can scaffold a project from it with a single command.

Generate a template skeleton

The wails3 generate template command produces a ready-to-customise template directory:

wails3 generate template -name MyTemplate

All flags:

Example with all flags:

wails3 generate template \
  -name "My Template" \
  -author "Your Name" \
  -description "React + custom setup" \
  -helpurl "https://github.com/yourname/my-template" \
  -version "v1.0.0" \
  -frontend ./my-existing-frontend

The generated directory looks like this:

MyTemplate/
├── template.yaml          # Template metadata — edit this
├── NEXTSTEPS.md           # Guidance for you as the template author — delete before publishing
├── README.md              # Shown to users after they create a project
├── main.go.tmpl           # Application entry point
├── greetservice.go        # Example Go service
├── go.mod.tmpl            # Go module file
├── go.sum.tmpl            # Go checksums
├── gitignore.tmpl         # Becomes .gitignore in generated projects
├── Taskfile.tmpl.yml      # Build task definitions
└── frontend/              # Your frontend code

Configure template metadata

Open template.yaml to set your template’s metadata:

# yaml-language-server: $schema=https://v3.wails.io/schemas/template.v3.json
name: "My Template"
shortname: my-template
author: Your Name
description: A template with my preferred setup
helpurl: https://github.com/yourname/my-template
version: v1.0.0
wailsVersion: 3

The wailsVersion field is required and must be 3. The # yaml-language-server comment at the top enables autocomplete and inline validation in VS Code (with the YAML extension) and JetBrains IDEs — you can leave it or remove it; it has no effect at runtime.

Customise the template

Frontend

The frontend/ directory is copied verbatim into every project created from your template. Replace the placeholder content with your actual frontend:

cd MyTemplate/frontend
npm create vite@latest .

npm install

wails3 generate template -name MyTemplate -frontend ./my-app/frontend

Build tasks

Taskfile.tmpl.yml defines the build workflow. Update the install:frontend:deps and build:frontend tasks to match your frontend toolchain:

tasks:
  install:frontend:deps:
    dir: frontend
    cmds:
      - npm install       # replace with pnpm install, yarn, etc.

  build:frontend:
    dir: frontend
    deps: [install:frontend:deps, generate:bindings]
    cmds:
      - npm run build     # replace with your build command

Go application

The main.go.tmpl file is the application entry point. It is processed by Wails’ template engine when a project is created — template variables like {{.ProductName}} are replaced with the values the user supplies.

To edit it as a real Go file (with IDE support), temporarily rename it to main.go, make your changes, then rename it back to main.go.tmpl before committing.

Template variables

These variables are available in any .tmpl file:

Test your template locally

Before publishing, test the template by creating a project from a local path:

wails3 init -n testproject -t /path/to/MyTemplate

Then verify the project works:

cd testproject
wails3 dev    # development mode with hot reload
wails3 build  # production binary

Check that:

• Frontend hot reload works
• Go code changes rebuild and relaunch the app
• The production binary in bin/ runs correctly

Publish on GitHub

git init
git add .
git commit -m "Initial template"
git remote add origin https://github.com/yourname/my-template.git
git push -u origin main

git tag v1.0.0
git push origin v1.0.0

Users can now create projects from your template:

# Latest commit on the default branch
wails3 init -n myapp -t https://github.com/yourname/my-template

# Pinned to a specific release tag
wails3 init -n myapp -t https://github.com/yourname/my-template@v1.0.0

Best practices

• Write a clear README.md — this is shown to users after they create a project. Explain how to run, build, and customise the project.
• Fill in helpurl — link to your repository or dedicated documentation. Users see it in the Wails CLI template list.
• Pin frontend dependency versions in package.json to avoid broken installs from upstream updates.
• Test before tagging — create a fresh project from the tagged release before announcing it to the community.
• Keep wailsVersion: 3 — this field tells Wails which major version the template targets. Do not change it.
• Update regularly — keep dependencies current and test against new Wails releases.