Background

PR #5337 adds Garble obfuscation support. It works, but the user experience requires two manual steps every build:

# Step 1 — generate stable ID file
wails3 generate bindings -obfuscated

# Step 2 — build with garble
wails3 build --obfuscated

This issue tracks making the workflow single-command and config-driven.

Problems to fix

1. build/config.yml has no obfuscation option

Users must remember to pass --obfuscated on every wails3 build invocation. There is no project-level setting to make it permanent.

Fix: add an obfuscated (bool) and garble_args (string) field to build/config.yml and the config struct so that wails3 build reads them automatically — no flag required.

2. Taskfile caching silently skips ID-file regeneration

generate:bindings has sources: / generates: set for Taskfile fingerprinting. wails_obfuscated.gen.go is not listed in generates:, so Taskfile does not know the file is missing and skips the generation step when Go sources are otherwise unchanged (e.g. first run after git clean, or first switch from a non-obfuscated build).

The build still compiles — but without the stable ID registrations, binding IDs resolve via the FNV hash on obfuscated names, which breaks at runtime.

Fix: add wails_obfuscated.gen.go (or a glob) to the generates: list in generate:bindings inside Taskfile.tmpl.yml so Taskfile detects its absence and forces regeneration.

3. OBFUSCATED is not explicitly forwarded through the dep chain

build:frontend calls generate:bindings as a dep and only forwards BUILD_FLAGS in its vars: block. OBFUSCATED reaches generate:bindings only via global CLI-var scoping — correct today but fragile and not obvious to contributors.

Fix: explicitly forward OBFUSCATED (and GARBLE_ARGS) in the vars: block where build:frontend calls generate:bindings.

Documentation that must be updated

The following docs pages must be updated as part of this issue (not as a follow-up):

• docs/src/content/docs/reference/cli.mdx

  • wails3 build row: remove "the only build-time flag is --tags"; document --obfuscated and --garbleargs
  • generate bindings row: add -obfuscated and -obfuscated-output to the flags list

• New guide: docs/src/content/docs/guides/build/obfuscation.mdx covering:

  • Prerequisites (garble @v0.16.0, Go 1.24+)
  • The json:"..." tag requirement on service struct fields (and why — garble renames exported fields when types cross an interface{} boundary)
  • Config-based workflow: set obfuscated: true in build/config.yml, then just wails3 build
  • What wails_obfuscated.gen.go is, whether to commit it, and what -obfuscated-output is for
  • Troubleshooting section

Acceptance criteria

• build/config.yml supports obfuscated: true and optional garble_args
• wails3 build (no flags) obfuscates when obfuscated: true is set in config
• wails3 generate bindings (no flags) emits wails_obfuscated.gen.go when obfuscated: true is set in config
• wails_obfuscated.gen.go is in the generates: list so Taskfile detects it as a target
• OBFUSCATED is explicitly forwarded in the build:frontend → generate:bindings dep vars: block
• Taskfile.tmpl.yml (and update build-assets) produces Taskfiles that include the above changes for new and existing projects
• CLI reference (cli.mdx) updated — wails3 build and generate bindings rows correct
• Obfuscation guide (guides/build/obfuscation.mdx) written and linked from the sidebar

Related

• PR feat(v3:obfuscation): add Garble support with stable binding IDs #5337 — the underlying feature this builds on
• Issue [v3] How to enable obfuscation #4563 — original obfuscation request