Auto-update, full + slim installers

How auto-update works

The frontend polls a Go method that hits the GitHub releases API. If a newer version is available the banner appears; the user clicks Update now, the modal opens, the new binary downloads to %TEMP%, and the running .exe gets atomically swapped with it. The whole cycle is ~20 lines of glue from the React side because all the hard parts live in updater.go.

The binary-swap trick (per OS)

Different OSes have different rules about overwriting a running executable. The updater branches accordingly:

Configure your release source

By default the updater points at the GitHub repo derived from your project name. Override with env vars if your repo lives somewhere else or you want to gate releases through a proxy:

# Required if your repo name differs from the project name
UPDATER_GITHUB_OWNER=acme-co
UPDATER_GITHUB_REPO=my-desktop-app

# Optional: PAT for private repos / higher rate limits
UPDATER_GITHUB_TOKEN=

# Optional: point at your own proxy instead of api.github.com
# (Lets you gate by min_supported_version, hide a PAT,
#  flip an emergency override env var without a redeploy.)
UPDATER_PROXY_URL=https://my-api.com/api/desktop

For most projects the GitHub defaults are enough. The proxy option matches the production pattern from the blog — useful when you have a paid customer base and want server-side gating.

Two Windows installers: full vs slim

Wails ships one installer template. We add a second so you can pick the right trade-off for each distribution channel.

Both installers default to %LOCALAPPDATA%\Programs\<ProjectName> — the Slack / Discord / VSCode convention. No admin required, so the in-app auto-updater can swap the binary without UAC.

Cutting a release

scripts/release-desktop.sh is the only command you need to know:

$scripts/release-desktop.sh 1.2.3

That does, in order:

1. Bumps wails.json productVersion + outputfilename
2. Bumps version.go's AppVersion constant
3. (Re)generates branded NSIS bitmaps from icon.ico via PowerShell
4. Downloads + caches the offline WebView2 runtime (~125 MB, first time only)
5. Runs wails build -nsis -platform windows/amd64 -trimpath -ldflags '-s -w'
6. Runs makensis on project-slim.nsi with the same raw binary
7. Tags v1.2.3, pushes the tag
8. gh release create uploads three assets: raw .exe (auto-updater uses this), full installer, slim installer

Frontend wiring (auto-mounted)

The scaffold mounts <UpdateBanner /> in your root layout already, so nothing for you to wire up. The hook polls every 6 hours; on focus / dismiss patterns are handled inside the banner. If you want a manual  "Check for updates" button in Settings, drop in:

import { useUpdateChecker } from '@/hooks/use-update-checker'
import { APP_VERSION } from '@/lib/version'

export function SettingsPage() {
  const { isChecking, checkNow, update, isUpdateAvailable } = useUpdateChecker()

  return (
    <div className="space-y-4">
      <p>Current version: <strong>v{APP_VERSION}</strong></p>
      <button
        onClick={() => checkNow()}
        disabled={isChecking}
        className="rounded-md bg-primary text-primary-foreground px-3 py-1.5 text-sm disabled:opacity-50"
      >
        {isChecking ? 'Checking…' : 'Check for updates'}
      </button>
      {isUpdateAvailable && update && (
        <p className="text-sm text-success">v{update.version} is available.</p>
      )}
    </div>
  )
}

Code signing (optional but recommended)

An unsigned .exe shows the Windows SmartScreen warning the first time a user runs it ("Windows protected your PC") — you lose installs and gain support tickets. A code-signing cert is ~$200/year from any reputable CA (DigiCert, Sectigo, SSL.com). Once you have a .pfx, add a step to the release script before the final gh release create:

# Sign the raw .exe and both installers
SIGN_CERT="${HOME}/.certs/code-signing.pfx"
SIGN_PASS="${CODE_SIGN_PASSWORD}"   # from env, not committed

for exe in "${RAW_EXE}" "${TARGET_FULL}" "${SLIM_TARGET}"; do
    signtool.exe sign \
        /f "${SIGN_CERT}" \
        /p "${SIGN_PASS}" \
        /tr http://timestamp.digicert.com \
        /td sha256 \
        /fd sha256 \
        "$exe"
done

For macOS notarization the same pattern applies with codesign + xcrun notarytool — covered in the dedicated macOS release guide (coming soon).

Emergency rollback / override

If you push a bad release and need to roll back without yanking the GitHub release: set UPDATER_PROXY_URL to a custom endpoint that returns the previous version. Or — if you're already using a proxy — flip an OVERRIDE_VERSION env var on your server and every client picks up the pinned version on its next 6-hour poll.