Understanding Wails: Go and TypeScript Interaction for Cross‑Platform Desktop Applications

Wails is a Go‑based cross‑platform desktop application framework that lets developers build user interfaces with modern front‑end technologies (e.g., Vue, React) while leveraging Go for efficient backend processing.

Core Functions

Lightweight Electron alternative : Reuses the operating system's native WebView (WebView2 on Windows, WebKit on macOS) instead of embedding Chromium, resulting in applications typically smaller than 10 MB.

Efficient front‑back communication : Provides a two‑way bridge where the front‑end can directly call Go methods and the back‑end can emit events to update the UI.

Cross‑platform support : Compiles to a single executable for Windows, macOS, and Linux with native window features.

Simple Principles

Front‑end rendering : Uses the OS native WebView to render HTML/CSS/JS, supporting frameworks like Vue and React.

Back‑end logic : Go handles business logic and exposes functions via wails.Bind() .

Communication mechanism : Bind call : Front‑end calls generated JavaScript wrappers that invoke Go methods and return a Promise. Event system : Publish/subscribe model for passing events and data between front‑end and back‑end.

Packaging : Front‑end assets are embedded into the Go binary to produce a platform‑specific executable.

Typical Scenarios

Lightweight utilities (system monitors, file managers).

Cross‑platform GUI applications requiring native performance.

Projects sensitive to binary size and startup speed, where Electron would be too heavy.

Comparison with Electron

Dimension

Wails

Electron

Runtime size

~10 MB (system WebView)

Hundreds of MB (embedded Chromium)

Performance

Higher (low resource consumption)

Lower (browser engine overhead)

Developer experience

Supports modern front‑end frameworks + Go type safety

Depends on Node.js ecosystem

Go ↔ TypeScript Interaction Process

Think of the Go code as the kitchen and the TypeScript/React front‑end as the dining area. The kitchen registers dishes (exported Go functions) which become a menu (TypeScript binding file). The front‑end orders a dish by calling the generated function, receives a Promise, and displays the result.

// Go code (kitchen) declares a dish
func (a *App) MakeBurger(ingredient string) string {
    return "Delicious " + ingredient + " burger"
}

// Auto‑generated TypeScript binding (menu card)
export function MakeBurger(ingredient: string): Promise
;

// Front‑end ordering the dish
import { MakeBurger } from '../wailsjs/go/main/App';
async function orderBurger() {
    const result = await MakeBurger("cheese");
    console.log(result); // "Delicious cheese burger"
}

The back‑end can also emit notifications that the front‑end listens for:

// Go emits an event
runtime.EventsEmit(a.ctx, "stock-warning", "Cheese is out")

// Front‑end registers a listener
import { EventsOn } from '../wailsjs/runtime';
EventsOn("stock-warning", (msg) => alert("Kitchen notice: " + msg));

Technical Details

Automatic code generation : Running wails build or wails dev scans Go source for exported functions and creates matching TypeScript definitions in frontend/wailsjs/go/ .

Runtime bridge : Go and JavaScript exchange JSON messages; complex types (structs, slices) are automatically marshaled.

Four Main Interaction Patterns

Direct function call (front‑end → back‑end).

Event system (bidirectional).

Calling front‑end functions from Go (back‑end → front‑end).

Special interactions such as window control and system dialogs.

Simple Application Example – Temperature Converter

// Go: temperature conversion functions
func (a *App) CelsiusToFahrenheit(c float64) float64 { return c*9/5 + 32 }
func (a *App) FahrenheitToCelsius(f float64) float64 { return (f-32)*5/9 }

// TypeScript React component using the bindings
import { CelsiusToFahrenheit, FahrenheitToCelsius } from '../wailsjs/go/main/App';
// UI with input, unit selector, and conversion button

Complex Application Example – File Manager

The back‑end (Go) provides services for directory listing, file reading/writing, and system dialogs, while the front‑end (Vue/TypeScript) presents the UI and handles user interactions. Key Go files include main.go , App.go , and file_service.go ; the front‑end consists of main.ts , App.vue , and generated TypeScript definitions.

Wails Internal Summary

Go is the engine, TypeScript is the dashboard : Go performs heavy computation, file I/O, and system calls; TypeScript renders the UI and captures user input.

Communication methods : Direct function calls, event emission, back‑end invoking front‑end functions, and broadcast events.

Automatic data conversion : Go structs ↔ TypeScript objects, slices ↔ arrays, primitive types map directly.

This design lets developers combine Go's system capabilities with modern front‑end frameworks to build powerful, lightweight desktop applications.