Tri's external memory

Wails - Session 1 Project Initialization & Backend Architecture

4 min read

Objectives

  • Understand the architecture of a Wails application.

  • Learn how a Wails program starts.

  • Understand the relationship between Go, Wails and WebView2.

  • Learn how the frontend calls Go functions.

High-Level Architecture

                 User
                   │
                   ▼
            Native Window
                   │
                   ▼
             WebView2 Engine
                   │
        HTML / CSS / JavaScript
                   │
             Wails JS Bridge
                   │
                   ▼
              Go Backend
                   │
                   ▼
          Windows Operating System

Unlike a web application:

  • No HTTP server

  • No REST API

  • No localhost

JavaScript communicates directly with Go through the Wails bridge.

Project Structure

AppName/
├── main.go
├── app.go
├── wails.json
├── build/
└── frontend/
    ├── src/
    ├── dist/
    ├── package.json
    └── wailsjs/

Responsibilities

ComponentResponsibility
main.goApplication entry point and wiring
app.goBackend business logic
frontend/srcUser Interface
frontend/wailsjsGenerated Go ↔ JavaScript bridge
buildPackaging resources
wails.jsonWails configuration

main.go

Responsibilities

main.go contains almost no application logic.

Its job is simply to assemble the application.

main()
    │
    ▼
NewApp()
    │
    ▼
wails.Run(...)

Embedded Frontend

//go:embed all:frontend/dist
var assets embed.FS

Go embeds all frontend files directly into the executable.

Result:

AppName.exe
├── Go code
├── HTML
├── CSS
├── JavaScript
└── Images

This allows distributing a single executable.

Creating the Backend

app := NewApp()

Creates the application’s backend object.

Starting Wails

wails.Run(...)

Internally Wails approximately performs:

Create Win32 Window
        │
        ▼
Create WebView2
        │
        ▼
Load embedded HTML
        │
        ▼
Initialize JS ↔ Go bridge
        │
        ▼
Display window

Asset Server

AssetServer: &assetserver.Options{
    Assets: assets,
}

Instead of serving files over HTTP:

Browser
    │
 HTTP
    │
Server

Wails serves directly from Go’s embedded filesystem:

WebView2
    │
embed.FS

Everything runs inside one process.

Window Configuration

Examples:

Title
Width
Height
BackgroundColour

These configure the native application window.

Startup Callback

OnStartup: app.startup

Executed once after application startup.

Typical responsibilities:

  • Load configuration

  • Initialize services

  • Open databases

  • Prepare application state

Binding Backend Objects

Bind: []interface{}{
    app,
}

Exports public methods of App to JavaScript.

This is the foundation of frontend ↔ backend communication.

app.go

Application State

type App struct {
    ctx context.Context
}

Currently the application stores only the Wails context.

Future AppName may contain:

App
├── ctx
├── config
├── history
├── bookmarks
├── settings
└── logger

Constructor

func NewApp() *App

Creates the backend object.

Keeping initialization outside main() keeps the entry point clean.

Startup

func (a *App) startup(ctx context.Context)

Stores the runtime context.

The context enables future access to:

  • Native dialogs

  • Clipboard

  • Notifications

  • Window operations

  • Application lifecycle

  • Runtime APIs

Backend Method

func (a *App) Greet(name string) string

This is only a demonstration.

The important concept is that JavaScript can call Go directly.

End-to-End Flow

When clicking Greet:

User
 │
 ▼
Button Click
 │
 ▼
JavaScript Event
 │
 ▼
Generated Wails Bridge
 │
 ▼
Go: App.Greet()
 │
 ▼
Return String
 │
 ▼
JavaScript receives result
 │
 ▼
Update UI

No HTTP.

No REST.

No manual JSON handling.

Traditional Web App vs Wails

Traditional

Browser
    │
 HTTP
    │
Backend
    │
 JSON
    │
Browser

Wails

WebView2
    │
Native Bridge
    │
Go Method
    │
Return Value

Mental Model

             main.go
                │
                ▼
          Create App
                │
                ▼
          wails.Run()
                │
     ┌──────────┴──────────┐
     ▼                     ▼
Native Window         WebView2
                              │
                              ▼
                  HTML/CSS/JavaScript
                              │
                              ▼
                     Generated Bridge
                              │
                              ▼
                        Go Backend

Key Takeaways

  • main.go wires the application together.

  • app.go contains backend logic.

  • The frontend is embedded into the executable.

  • Wails creates a native Win32 window.

  • Rendering is provided by Microsoft WebView2.

  • JavaScript communicates directly with Go.

  • Bind exposes Go methods to JavaScript.

  • startup() is the initialization hook.

  • App represents the backend state.

Questions for Reflection

  1. Why does Wails not need an HTTP server?

  2. What is the purpose of Bind?

  3. Why is context.Context stored in App?

  4. What files become embedded into the executable?

  5. Which file is responsible for wiring the application together?

  6. If we add OpenLab() to App, how could the frontend invoke it?

Next Session

Frontend Architecture

Topics:

  • frontend/src

  • Generated wailsjs

  • JavaScript → Go bridge

  • Go → JavaScript return values

  • Complete request/response lifecycle

Graph View

Backlinks