Wails

What I do

• Set up and validate Wails prerequisites (Go, Node/NPM, platform deps)
• Create projects with wails init and pick templates/frameworks
• Run dev workflows with wails dev and explain live reload/browser mode
• Build production binaries with wails build and platform-specific flags
• Use runtime APIs (window, menu, dialog, events, log, browser, clipboard, screen, drag-and-drop)
• Configure wails.json and application options when needed
• Apply frontend script injection rules and external dev server setups
• Use guides for platform-specific packaging, signing, and troubleshooting
• Point to CLI, options, menus, project config, and runtime references

When to use me

Use this skill for Wails app creation, local development, build issues, and CLI usage. Ask clarifying questions if platform, template, or Wails version is unclear.

Workflow

1. Identify the target OS and Wails version.
2. Confirm prerequisites: Go 1.21+, Node/NPM, and platform deps (xcode, WebView2, GTK/WebKit).
3. For new apps, choose a template and run wails init -n <name> -t <template>.
4. For dev, use wails dev and describe browser dev server at http://localhost:34115.
5. For builds, use wails build; on Linux with newer distros, add -tags webkit2_41 when needed.
6. For runtime usage, use the Go runtime package github.com/wailsapp/wails/v2/pkg/runtime or window.runtime in JS.
7. For events, prefer EventsOn, EventsOnce, EventsOnMultiple, EventsOff, and EventsEmit to coordinate Go/JS.
8. If issues arise, run wails doctor and resolve missing deps.

Architecture

• Wails is a Go app with a WebView frontend and a shared runtime library.
• Go methods are bound and exposed to JS with autogenerated wailsjs modules.
• Runtime methods are available in Go via runtime and in JS via window.runtime.

Key commands

go install github.com/wailsapp/wails/v2/cmd/wails@latest
wails doctor
wails init -n myproject -t <template>
wails dev
wails build

CLI highlights

• wails init: -t template (local or remote GitHub URL), -n name, -d dir, -ide.
• wails dev: -assetdir, -wailsjsdir, -frontenddevserverurl, -browser, -loglevel.
• wails build: -platform, -tags, -obfuscated, -upx, -nsis, -devtools, -debug.
• wails generate module: regenerate wailsjs without running dev.
• wails generate template: scaffold or derive templates from a frontend project.

Runtime API map

• Events: EventsOn, EventsOff, EventsOnce, EventsOnMultiple, EventsEmit.
• Log: LogTrace, LogDebug, LogInfo, LogWarning, LogError, LogFatal, LogSetLogLevel.
• Window: title, size, position, fullscreen/maximise/minimise, show/hide, reload, exec JS.
• Dialog: open/save dialogs, message dialogs (Go only).
• Menu: set/update application menu (Go only).
• Browser: open URL in system browser.
• Clipboard: get/set text.
• Screen: list connected screens.
• Drag and Drop: OnFileDrop, OnFileDropOff (requires EnableFileDrop).

Config and options

• wails.json: frontend dirs/build scripts, assetdir, reload dirs, dev server URL, output name, build tags, hooks, info/associations/protocols, bindings ts generation.
• App options: window size, frame, start state, background, always-on-top, menus, logging, callbacks, bindings, single-instance lock, drag-and-drop, default context menu, fraud detection.
• OS-specific options: Windows (WebView2, theme, backdrop, zoom), Mac (title bar, appearance, transparency, about), Linux (icons, GPU policy).

Frontend integration

• Default script injection adds /wails/ipc.js and /wails/runtime.js to index.html.
• Use <meta name="wails-options" content="noautoinject"> to opt out and inject manually.
• For external dev servers (example: CRA), configure frontend:dev:watcher and frontend:dev:serverUrl.

Guides quick hits

• Angular: set frontend:build, frontend:install, frontend:dev:watcher, frontend:dev:serverUrl for ng.
• Routing: prefer hash-based routing (Vue hash, Angular useHash, React HashRouter, Svelte SPA router).
• Frameless: Frameless: true, use --wails-draggable:drag and --wails-draggable:no-drag.
• Overscroll: disable bounce with html { height: 100%; overflow: hidden; }.
• Dynamic assets: use AssetServer.Handler to serve fallback/dynamic content (watch Vite v5 warning).
• Obfuscation: wails build -obfuscated with optional -garbleargs and rely on wailsjs bindings.
• Single instance lock: SingleInstanceLock with UniqueId and OnSecondInstanceLaunch.
• Custom protocols and file associations: define info.protocols / info.fileAssociations, platform specifics.
• NSIS installer: install NSIS, build with wails build -nsis.
• Local dev on Wails master/PRs: go install from cloned repo and use replace in go.mod.
• Linux notes: distro package support, GStreamer plugin for media, NixOS font-size workaround.
• IDEs: -ide vscode or -ide goland; adjust VS Code tasks for frontend builds.
• Tutorials: Hello World and Dogs API show basic init/build/dev flows.

Step-by-step playbooks

Angular dev server

1. Set frontend:build to npx ng build and frontend:install to npm install in wails.json.
2. Add frontend:dev:watcher = npx ng serve and frontend:dev:serverUrl = http://localhost:4200.
3. Run wails dev.

SvelteKit integration

1. wails init -n <name> -t svelte.
2. Delete frontend/, then npx sv create frontend.
3. In wails.json add "wailsjsdir": "./frontend/src/lib" and update package manager commands.
4. In main.go change //go:embed all:frontend/dist to //go:embed all:frontend/build.
5. Update .gitignore from frontend/dist to frontend/build.
6. In frontend/, install deps, replace adapter with @sveltejs/adapter-static.
7. Add src/routes/+layout.ts with export const prerender = true and export const ssr = false.
8. Run wails dev.

Frameless window drag zones

1. Set Frameless: true in options.App.
2. Use --wails-draggable:drag on the container.
3. Use --wails-draggable:no-drag on interactive elements.
4. If CSS variables are unavailable, set CSSDragProperty and CSSDragValue in options.

Dynamic assets

1. Configure AssetServer.Handler in options.App.
2. Serve missing assets or handle non-GET requests in the handler.
3. Avoid exposing arbitrary filesystem paths without authorization checks.

Obfuscated builds

1. Build with wails build -obfuscated (optional -garbleargs).
2. Ensure frontend calls use generated wailsjs bindings (not window.go names).

Single instance lock

1. Add SingleInstanceLock with a UUID UniqueId.
2. Use OnSecondInstanceLaunch to process args and bring window forward.
3. Treat second-instance data as untrusted input.

Custom protocols

1. Add info.protocols in wails.json with scheme, description, role.
2. macOS: handle Mac.OnUrlOpen.
3. Windows: use NSIS installer; parse command-line args or use single instance lock.
4. Linux: create .desktop and mime entries via packaging (eg. nfpm).

File associations

1. Add info.fileAssociations in wails.json with ext, name, iconName, description, role.
2. macOS: handle Mac.OnFileOpen.
3. Windows: use NSIS installer; parse args or use single instance lock.
4. Linux: create mime files, desktop entry, icons, and package scripts.

NSIS installer

1. Install NSIS (scoop/winget/choco/brew).
2. Configure build/windows/installer info from wails.json.
3. Run wails build -nsis and use build/bin output.

Local development against Wails master/PR

1. Clone github.com/wailsapp/wails, checkout target branch/PR.
2. cd v2/cmd/wails && go install.
3. Add replace github.com/wailsapp/wails/v2 => <clonedir>/wails/v2 in your app go.mod.
4. Revert by reinstalling CLI from @latest and removing replace.

Extended guides

Code signing (Windows)

1. Base64-encode your .pfx/.p12 certificate and store as GitHub Actions secrets.
2. Build the app in CI, then use signtool.exe with /fd sha256 and timestamp server.
3. If using Actions, ensure the signing step runs after wails build.

Code signing (macOS)

1. Export your Apple Developer cert (.p12) and base64-encode it.
2. Use gon for signing + notarization; configure build/darwin/gon-sign.json and entitlements.
3. Import certs via Apple-Actions/import-codesign-certs@v1, then run gon.

Mac App Store submission

1. Create App ID, certs, provisioning profile, and App Store Connect entry.
2. Add build/darwin/entitlements.plist with App Sandbox settings.
3. Build and sign with wails build -platform darwin/universal, then codesign and productbuild.
4. Upload via Transporter and attach build in App Store Connect.

GitHub Actions cross-platform builds

1. Use a matrix for linux/amd64, windows/amd64, darwin/universal.
2. Cache node and Go deps; set NODE_OPTIONS=--max-old-space-size=4096 if needed.
3. Run wails build (or dAppServer/wails-build-action) and upload build/bin/*.

WebView2 strategies (Windows)

1. Use wails build -webview2 <download|embed|browser|error>.
2. For fixed runtime, set WebviewBrowserPath and bundle the runtime.
3. If running as admin, set WebviewUserDataPath to a shared location.

Manual build process (decomposed)

1. Install frontend deps (unless -s or no frontend:install).
2. Build frontend (unless -s or no frontend:build).
3. Generate assets/icons (Windows uses winicon + winres).
4. Compile Go (-tags dev with -gcflags for dev, -tags desktop,production for prod).
5. Optional UPX compression (-upx).

Templates

1. wails generate template -name <name> to scaffold a template.
2. For existing frontend, use -frontend path and update template files.
3. Test with wails init -t <path> then wails build.
4. Publish to GitHub and submit to Community Templates.

IDE setup

1. Use wails init -ide vscode or -ide goland.
2. For VS Code, update .vscode/tasks.json to include frontend install/build steps.
3. For Vue + Vetur, add vetur.config.js pointing at frontend/.

Troubleshooting highlights

1. White screen: verify //go:embed all:frontend/dist and assets in frontend/dist.
2. macOS blank screen: add NSAllowsLocalNetworking to Info.plist.
3. Windows icon cache: delete %LOCALAPPDATA%/IconCache.db.
4. Variadic args: pass array without spread to backend.
5. Stuck on bindings: ensure app exits after wails.Run().
6. macOS compile errors: update Xcode CLI tools or switch toolchain path.
7. WebView2 missing: install correct architecture runtime.

Routing patterns

1. Vue: createWebHashHistory().
2. Angular: RouterModule.forRoot(routes, { useHash: true }).
3. React: HashRouter.
4. Svelte: svelte-spa-router.

Mouse buttons (frameless apps)

1. Use mousedown listener and inspect event.button for button index.

NixOS font-size bug

1. Add XDG_DATA_DIRS and GIO_MODULE_DIR to your devShell hook.

Notes

• Wails generates Go bindings and TypeScript models for frontend calls.
• Project layout includes main.go, frontend/, build/, and wails.json.
• Runtime methods need a context from OnStartup or OnDomReady.
• Events can be emitted from Go or JavaScript with optional data payloads.
• Manual builds follow install -> build frontend -> generate assets -> compile -> optional UPX.
• Windows WebView2 can be handled via -webview2 strategies or fixed runtime.
• Use guides for code signing, Mac App Store submission, and GitHub Actions builds.
• Use CLI, options, menus, project config, and runtime references for details.