Build & Distribution

Development vs Production

Until now, you've been running your app in development mode with grit start. Development mode includes tools that help you build the app but are not needed by end users:

Building Your App

To compile your app into a production binary, run:

grit compile

Or use the Wails command directly:

wails build

Here is what happens during the build:

• 1. Vite builds React — bundles, minifies, and optimizes all JavaScript, CSS, and assets
• 2. Go embeds the frontend — the built React files are embedded into the Go binary using go:embed
• 3. Go compiles to native code — the entire application (backend + embedded frontend) becomes a single executable

The output binary is placed in the build/bin/ directory:

build/
└── bin/
    └── myapp.exe     # Windows
    └── myapp         # macOS / Linux

Platform Targets

Wails can build for different operating systems and architectures:

# Build for your current platform (default)
wails build

# Build for Windows (64-bit)
wails build -platform windows/amd64

# Build for macOS (Intel)
wails build -platform darwin/amd64

# Build for macOS (Apple Silicon / M1, M2, M3)
wails build -platform darwin/arm64

# Build for Linux (64-bit)
wails build -platform linux/amd64

App Icon

Every desktop app needs an icon — it appears in the taskbar, dock, file explorer, and the window title bar. Wails uses icon files in the build/ directory:

build/
├── appicon.png        # 1024x1024 PNG (used for all platforms)
├── windows/
│   └── icon.ico       # Windows icon (multi-size)
├── darwin/
│   └── appicon.icns   # macOS icon (multi-size)
└── linux/
    └── appicon.png    # Linux icon

To change the icon:

• 1. Create a 1024x1024 pixel PNG image for your app icon
• 2. Replace build/appicon.png with your new image
• 3. Rebuild with grit compile — Wails converts it to platform-specific formats

Window Configuration

The wails.json file controls how the production window appears:

{
  "name": "My App",
  "width": 1024,
  "height": 768,
  "minWidth": 800,
  "minHeight": 600,
  "frameless": true,
  "fullscreen": false,
  "resizable": true
}

The name field is what appears in the operating system's task manager and window list. The size settings define the default dimensions and minimum size.

File Size

A typical Grit desktop app binary is 15-30 MB. This includes the entire Go backend, all React code, CSS, and embedded assets. For comparison, an Electron app with similar features would be 100-200 MB.

You can reduce the binary size by stripping debug symbols:

# Build with stripped debug symbols (smaller binary)
wails build -ldflags "-s -w"

# -s removes the symbol table
# -w removes DWARF debugging information

For even smaller binaries, you can use UPX compression (a tool that compresses executables):

# Install UPX (if not already installed)
# Windows: scoop install upx
# macOS: brew install upx
# Linux: apt install upx

# Compress the binary
upx --best build/bin/myapp.exe

Typical size reduction:

Distribution

Once your app is compiled, you need to get it to your users. There are several distribution methods:

Direct Download

The simplest method — upload the binary to your website, GitHub Releases, or a file hosting service. Users download the file and run it. No installer needed.

Windows Installer (NSIS)

Wails can generate an NSIS installer for Windows. This creates a .exe installer that adds your app to the Start Menu, creates desktop shortcuts, and supports uninstallation:

wails build -nsis

macOS DMG

On macOS, Wails builds a .app bundle. You can package it into a .dmg disk image for distribution — the standard macOS app distribution format.

Linux AppImage

For Linux, you can package the binary as an AppImage — a single executable that works on most Linux distributions without installation.

Code Signing

• • Windows — requires a code signing certificate ($200-400/year) from a Certificate Authority
• • macOS — requires an Apple Developer account ($99/year) and notarization through Apple's servers
• • Linux — code signing is optional; most Linux users install from package managers or trust direct downloads

Publishing with GitHub Releases

The most common way to distribute desktop apps for open-source projects is GitHub Releases. You build for each platform and upload the binaries:

# Build for your platform
grit compile

# Create a GitHub release (using gh CLI)
gh release create v1.0.0 build/bin/myapp.exe --title "v1.0.0" --notes "Initial release"

# Or upload multiple platform binaries
gh release create v1.0.0   build/bin/myapp-windows-amd64.exe   build/bin/myapp-darwin-amd64   build/bin/myapp-linux-amd64   --title "v1.0.0" --notes "Initial release"

Users visit your GitHub repository's Releases page and download the binary for their platform.

What You Learned

• The difference between development builds and production builds
• How to compile your app with grit compile or wails build
• Platform targets — building for Windows, macOS, and Linux
• How to customize the app icon
• Window configuration in wails.json
• Optimizing binary size with -ldflags "-s -w" and UPX
• Distribution methods — direct download, NSIS installer, DMG, AppImage
• What code signing is and when you need it

Course Complete

Congratulations — you've completed the entire Grit Desktop course track. You now know how to:

• • Scaffold a desktop app with grit new-desktop
• • Generate full CRUD resources with Wails bindings
• • Customize the UI with frameless windows, themes, and shadcn/ui
• • Export data to PDF, Excel, and CSV
• • Compile and distribute a native binary

Next steps: build something real. A personal finance tracker, a note-taking app, a project management tool, a CRM for your business — the possibilities are endless. Every app follows the same pattern: scaffold, generate resources, customize the UI, export data, and ship.