Your First Desktop App

What is a Desktop App?

Desktop apps are different from web apps in several important ways:

• • They run locally — no browser needed, no internet required (unless your app needs it)
• • They can access the filesystem — read and write files on the user's computer
• • They feel faster — no network latency between the UI and backend
• • They are distributed as a single file — users download one executable and run it

Grit uses Wails to build desktop apps. You write Go for the backend and React for the UI — the same languages you already know from Grit web.

What is Wails?

Wails works by embedding a webview (a lightweight browser engine) inside a native window. Your React app runs in this webview, and Wails creates a bridge so JavaScript can call Go functions directly:

• • Go side: You write normal Go methods like GetUsers() or CreateBlog(input)
• • React side: You import and call them as if they were local functions — const users = await GetUsers()
• • No HTTP layer: No REST endpoints, no fetch(), no axios — direct function calls over an internal bridge

Learn more at wails.io. Wails supports Windows, macOS, and Linux from a single codebase.

Prerequisites

You need the same tools as Grit web (Go, Node.js, pnpm) plus one more — the Wails CLI:

Install the Wails CLI with:

go install github.com/wailsapp/wails/v2/cmd/wails@latest

After installation, verify everything is working:

wails doctor

The wails doctor command checks your system for all required dependencies (Go, Node, npm/pnpm, platform-specific build tools) and reports any issues.

Scaffold a Desktop App

The command for desktop apps is grit new-desktop — this is different from grit new which creates a web monorepo:

grit new-desktop myapp

After running the command, Grit creates a complete desktop project with authentication, blog CRUD, contact CRUD, a dark theme, and a SQLite database — all wired up and ready to run.

Project Structure

A Grit desktop project has a flat, simple structure:

notes-app/
├── main.go          <- Wails bootstrap + Go embed
├── app.go           <- Bound methods (Go functions callable from React)
├── internal/        <- Go backend (models, services, config, db)
├── frontend/        <- React app (Vite + TanStack Router)
├── wails.json       <- Wails configuration
└── .env             <- Environment variables

Compare this to a Grit web project which has apps/api, apps/web, apps/admin, and packages/shared. A desktop project is much simpler — everything is in one place.

The key file is app.go — this is where all your Go methods that React can call are defined. Every public method on the App struct becomes available in the frontend:

type App struct {
    ctx         context.Context
    authService *services.AuthService
    blogService *services.BlogService
}

// React can call: Login({ email, password })
func (a *App) Login(input types.LoginInput) (*types.AuthResponse, error) {
    return a.authService.Login(input)
}

// React can call: GetBlogs()
func (a *App) GetBlogs() ([]models.Blog, error) {
    return a.blogService.List()
}

Running in Dev Mode

Start your desktop app with either command:

cd notes-app
grit start

Or use the Wails command directly:

wails dev

When you run grit start, a native desktop window opens with your app. The frontend dev server runs at localhost:34115 (you can also open it in a browser for debugging).

SQLite Database

Desktop apps use SQLite instead of PostgreSQL because users should not need to install a database server. The database file travels with the app — it's just a file on disk:

DB_PATH=./data.db

When the app starts, GORM automatically creates the .db file and runs migrations. You can browse the database with GORM Studio:

grit studio

Tour the App

Your scaffolded desktop app comes with everything you need to start building:

• • Login and Register pages — local authentication with bcrypt password hashing
• • Dashboard — stats cards showing total blogs, contacts, and recent activity
• • Blog CRUD — create, read, update, and delete blog posts
• • Contact CRUD — manage a contacts list with full CRUD operations
• • Sidebar navigation — collapsible sidebar with icons for every section
• • Dark theme — premium dark UI using Grit's design system

The .env File

Desktop apps have a simpler .env file compared to web projects — no database URLs, no Redis, no S3 storage:

APP_NAME=notes-app
JWT_SECRET=your-secret-key-change-in-production
DB_PATH=./data.db
TOTP_ISSUER=notes-app

• • APP_NAME — your application name, shown in the title bar
• • JWT_SECRET — secret key for signing authentication tokens
• • DB_PATH — path to the SQLite database file
• • TOTP_ISSUER — name shown in authenticator apps for two-factor auth

Essential Commands

Here are the commands you'll use every day when building desktop apps:

What You Learned

• What desktop apps are and how they differ from web apps
• What Wails is — Go + React desktop framework with direct function calls
• How to install the Wails CLI and verify with wails doctor
• How to scaffold a desktop app with grit new-desktop
• The flat project structure (main.go, app.go, internal/, frontend/)
• How Wails bindings work — Go methods callable from React
• How to run in dev mode with grit start and hot reload
• SQLite as the database — file-based, no server required
• The essential CLI commands for desktop development