|
| 1 | +--- |
| 2 | +title: Creating Custom Templates |
| 3 | +description: Learn how to create and customise your own Wails v3 templates |
| 4 | +sidebar: |
| 5 | + order: 50 |
| 6 | +--- |
| 7 | + |
| 8 | +This guide will walk you through the process of creating a custom template for Wails v3. |
| 9 | + |
| 10 | +## Why would I make a custom template? |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +### 1. Generating a Template |
| 15 | + |
| 16 | +To create a custom template, you can use the `wails generate template` command: |
| 17 | + |
| 18 | +```bash |
| 19 | +wails3 generate template -name mytemplate |
| 20 | +``` |
| 21 | + |
| 22 | +This will create a new directory called "mytemplate" in your current directory. |
| 23 | + |
| 24 | +The `wails3 generate template` command supports the following options: |
| 25 | + |
| 26 | +| Option | Description | Default | |
| 27 | +|----------------|---------------------------------------------------|-------------------| |
| 28 | +| `-name` | The name of your template (required) | - | |
| 29 | +| `-frontend` | Path to an existing frontend directory to include | - | |
| 30 | +| `-author` | The author of the template | - | |
| 31 | +| `-description` | A description of the template | - | |
| 32 | +| `-helpurl` | URL for template documentation | - | |
| 33 | +| `-dir` | Directory to generate the template in | Current directory | |
| 34 | +| `-version` | Template version | v0.0.1 | |
| 35 | + |
| 36 | +For example, to create a template with all options: |
| 37 | + |
| 38 | +```bash |
| 39 | +wails3 generate template \ |
| 40 | + -name "My Custom Template" \ |
| 41 | + -frontend ./my-existing-frontend \ |
| 42 | + -author "Your Name" \ |
| 43 | + -description "A template with my preferred setup" \ |
| 44 | + -helpurl "https://github.com/yourusername/template-docs" \ |
| 45 | + -dir ./templates \ |
| 46 | + -version "v1.0.0" |
| 47 | +``` |
| 48 | + |
| 49 | + :::tip |
| 50 | + Using the `-frontend` option will copy an existing web frontend project into the template. |
| 51 | + ::: |
| 52 | + |
| 53 | +### 2. Configure Template Metadata |
| 54 | + |
| 55 | +If you didn't specify the template configuration when generating the template, you can update the `template.json` file in the template directory: |
| 56 | + |
| 57 | +```json5 |
| 58 | +{ |
| 59 | + "name": "Your Template Name", // Display name of your template |
| 60 | + "shortname": "template-shortname", // Used when referencing your template |
| 61 | + "author": "Your Name", // Template author |
| 62 | + "description": "Template description", // Template description |
| 63 | + "helpurl": "https://your-docs.com", // Documentation URL |
| 64 | + "version": "v0.0.1", // Template version |
| 65 | + "schema": 3 // Must be kept as 3 for Wails v3 |
| 66 | +} |
| 67 | +``` |
| 68 | +:::caution |
| 69 | +The `schema` field must remain set to `3` for compatibility with Wails v3. |
| 70 | +::: |
| 71 | + |
| 72 | +### 3. Set Up Build Tasks |
| 73 | + |
| 74 | +In the `build` directory is `Taskfile.yml` where you can define your template's build process. |
| 75 | +This file uses [Task](https://taskfile.dev) for build automation. The key steps are: |
| 76 | + |
| 77 | +```yaml |
| 78 | +tasks: |
| 79 | + install:frontend:deps: |
| 80 | + summary: Install frontend dependencies |
| 81 | + dir: frontend |
| 82 | + sources: |
| 83 | + - package.json |
| 84 | + - package-lock.json |
| 85 | + generates: |
| 86 | + - node_modules/* |
| 87 | + preconditions: |
| 88 | + - sh: npm version |
| 89 | + msg: "Looks like npm isn't installed. Npm is part of the Node installer: https://nodejs.org/en/download/" |
| 90 | + cmds: |
| 91 | + - npm install |
| 92 | + |
| 93 | + build:frontend: |
| 94 | + summary: Build the frontend project |
| 95 | + dir: frontend |
| 96 | + sources: |
| 97 | + - "**/*" |
| 98 | + generates: |
| 99 | + - dist/* |
| 100 | + deps: |
| 101 | + - task: install:frontend:deps |
| 102 | + - task: generate:bindings |
| 103 | + cmds: |
| 104 | + - npm run build -q |
| 105 | + |
| 106 | + |
| 107 | +``` |
| 108 | + |
| 109 | +### 4. Frontend Setup |
| 110 | + |
| 111 | +If you did not use `-frontend` when generating the template, you need to add frontend files to your template. |
| 112 | + |
| 113 | +There are a number of ways to set up your frontend: starting from scratch or using an existing framework. |
| 114 | + |
| 115 | +import { Tabs, TabItem } from '@astrojs/starlight/components'; |
| 116 | + |
| 117 | +<Tabs> |
| 118 | + <TabItem label="Start from Scratch"> |
| 119 | + If you want to start from scratch, you can create your frontend project just like you would for any web application. |
| 120 | + The `frontend` directory in your template is just a regular directory where you can set up your preferred |
| 121 | + development environment. You might want to use build tools like Vite, webpack, or even just plain HTML, CSS, and |
| 122 | + JavaScript - it's entirely up to you! |
| 123 | + |
| 124 | + For example, if you're using Vite, you could navigate to the `frontend` directory and run: |
| 125 | + |
| 126 | + ```bash |
| 127 | + npm create vite@latest . |
| 128 | + ``` |
| 129 | + |
| 130 | + 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. |
| 131 | + </TabItem> |
| 132 | + <TabItem label="Use Existing Framework"> |
| 133 | + For this example, we'll use [Vite](https://vitejs.dev/) to set up a React frontend project: |
| 134 | + |
| 135 | + ```bash |
| 136 | + npm create vite@latest frontend -- --template react |
| 137 | + cd frontend |
| 138 | + npm install |
| 139 | + ``` |
| 140 | + |
| 141 | + </TabItem> |
| 142 | +</Tabs> |
| 143 | + |
| 144 | + |
| 145 | +Now you have the frontend files in place, update `common/Taskfile.yml` with the appropriate commands: |
| 146 | + ```yaml |
| 147 | + tasks: |
| 148 | + install:frontend:deps: |
| 149 | + summary: Install frontend dependencies |
| 150 | + dir: frontend |
| 151 | + sources: |
| 152 | + - package.json |
| 153 | + - package-lock.json |
| 154 | + generates: |
| 155 | + - node_modules/* |
| 156 | + preconditions: |
| 157 | + - sh: npm version |
| 158 | + msg: "Looks like npm isn't installed. Npm is part of the Node installer: https://nodejs.org/en/download/" |
| 159 | + cmds: |
| 160 | + - npm install |
| 161 | + |
| 162 | + build:frontend: |
| 163 | + summary: Build the frontend project |
| 164 | + dir: frontend |
| 165 | + sources: |
| 166 | + - "**/*" |
| 167 | + generates: |
| 168 | + - dist/* |
| 169 | + deps: |
| 170 | + - task: install:frontend:deps |
| 171 | + - task: generate:bindings |
| 172 | + cmds: |
| 173 | + - npm run build -q |
| 174 | + ``` |
| 175 | +
|
| 176 | + :::note |
| 177 | + For this example, the default Tasks do not need updating as they use the standard `npm install` and `npm run build` commands. |
| 178 | + ::: |
| 179 | + |
| 180 | +### 5. Configure the Go Application |
| 181 | + |
| 182 | +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. |
| 183 | + |
| 184 | +#### Template Variables |
| 185 | + |
| 186 | +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: |
| 187 | + |
| 188 | +| Variable | Description | Example | |
| 189 | +|----------------------|----------------------------------|-----------------------------------| |
| 190 | +| `Name` | The name of the project | `"MyApp"` | |
| 191 | +| `BinaryName` | The name of the generated binary | `"myapp"` | |
| 192 | +| `ProductName` | The product name | `"My Application"` | |
| 193 | +| `ProductDescription` | Description of the product | `"An awesome application"` | |
| 194 | +| `ProductVersion` | Version of the product | `"1.0.0"` | |
| 195 | +| `ProductCompany` | Company name | `"My Company Ltd"` | |
| 196 | +| `ProductCopyright` | Copyright information | `"Copyright 2024 My Company Ltd"` | |
| 197 | +| `ProductComments` | Additional product comments | `"Built with Wails"` | |
| 198 | +| `ProductIdentifier` | Unique product identifier | `"com.mycompany.myapp"` | |
| 199 | +| `Typescript` | Whether TypeScript is being used | `true` or `false` | |
| 200 | +| `WailsVersion` | The version of Wails being used | `"3.0.0"` | |
| 201 | + |
| 202 | +You can use these variables in your template files using Go's template syntax: |
| 203 | + |
| 204 | +```go |
| 205 | +// main.go.tmpl |
| 206 | +package main |
| 207 | +
|
| 208 | +import ( |
| 209 | + "github.com/wailsapp/wails/v3/pkg/application" |
| 210 | +) |
| 211 | +
|
| 212 | +func main() { |
| 213 | + app := application.New(application.Options{ |
| 214 | + Name: "{{.ProductName}}", |
| 215 | + Description: "{{.ProductDescription}}", |
| 216 | + }) |
| 217 | + // ... |
| 218 | +} |
| 219 | +``` |
| 220 | + |
| 221 | + :::tip |
| 222 | + Templating can be applied to any file in your template, even html files, so long as the filename has `.tmpl` in its name. |
| 223 | + ::: |
| 224 | + |
| 225 | +### 6. Testing Your Template |
| 226 | + |
| 227 | +To test your template: |
| 228 | + |
| 229 | +1. Generate a project using your template: `wails3 init -n testproject -t path/to/your/template` |
| 230 | +2. Run `wails3 build` to generate the production build and make sure the binary in `bin` runs correctly |
| 231 | +3. Run `wails3 dev` to start the development server. |
| 232 | +4. Test that changes to the frontend code are reflected in the application. |
| 233 | +5. Test that changes to the Go code rebuild and relaunch the application |
| 234 | + |
| 235 | +### 7. Sharing Your Template |
| 236 | + |
| 237 | +Once your template is ready, you can share it with the community by hosting it on GitHub. Here's how: |
| 238 | + |
| 239 | +1. Create a new GitHub repository for your template |
| 240 | +2. Push your template code to the repository |
| 241 | +3. Tag your releases using semantic versioning (e.g., v1.0.0) |
| 242 | + |
| 243 | +Users can then use your template directly from GitHub using the HTTPS URL: |
| 244 | + |
| 245 | +```bash |
| 246 | +wails3 init -n myapp -t https://github.com/yourusername/your-template |
| 247 | +``` |
| 248 | + |
| 249 | +You can also specify a particular version using the URL format: |
| 250 | + |
| 251 | +```bash |
| 252 | +# Use a specific version tag |
| 253 | +wails3 init -n myapp -t https://github.com/yourusername/your-template/releases/tag/v1.0.0 |
| 254 | +
|
| 255 | +# Use a specific branch |
| 256 | +wails3 init -n myapp -t https://github.com/yourusername/your-template/tree/main |
| 257 | +``` |
| 258 | + |
| 259 | +To test your template before sharing: |
| 260 | + |
| 261 | +1. Push your changes to GitHub |
| 262 | +2. Create a new test project using the HTTPS URL: |
| 263 | + ```bash |
| 264 | + wails3 init -n testapp -t https://github.com/yourusername/your-template |
| 265 | + ``` |
| 266 | +3. Verify that all files are correctly generated |
| 267 | +4. Test the build and development workflow as described in the testing section |
| 268 | + |
| 269 | + :::note |
| 270 | + Make sure your repository is public if you want others to use your template. |
| 271 | + ::: |
| 272 | + |
| 273 | +For more information, visit the [Wails documentation](https://wails.io) |
| 274 | + |
| 275 | + |
| 276 | +## Best Practices |
| 277 | + |
| 278 | +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: |
| 279 | + |
| 280 | +1. **Make Your Template Easy to Understand** |
| 281 | + - Write a clear, helpful README.md that gets users started quickly |
| 282 | + - Add comments in your config files to explain the "why" behind your choices |
| 283 | + - Show examples of common customisations - users love to see real-world use cases! |
| 284 | + |
| 285 | +2. **Keep Dependencies Happy** |
| 286 | + - Stay on top of your frontend package updates |
| 287 | + - Lock down specific versions in package.json to avoid surprises |
| 288 | + - Let users know upfront what they'll need to have installed |
| 289 | + |
| 290 | +3. **Love Your Template** |
| 291 | + - Keep it fresh with regular updates |
| 292 | + - Give it a thorough test drive before sharing |
| 293 | + - Share it with the Wails community - we'd love to see what you create! |
0 commit comments