Desktop (Wails)

Getting Started with Desktop

Scaffold a native desktop application with one command. This guide walks you through prerequisites, project creation, development workflow, and running GORM Studio.

Prerequisites

Make sure the following tools are installed before creating a desktop project:

Go1.21+

go version

Node.js18+

node --version

Grit CLILatest

grit --help

Wails CLIv2

wails version

Install the Wails CLI if you don't have it yet:

Terminal

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

Run wails doctor to verify your environment. It checks for Go, Node.js, npm/pnpm, and platform-specific build tools (GCC on Linux, Xcode on macOS, or WebView2 on Windows).

Scaffold the Project

Create a new desktop project with the Grit CLI. This generates a complete Wails application with Go backend, React frontend, authentication, CRUD resources, and all batteries included.

Terminal

$grit new-desktop myapp

Project Structure

The scaffolded project has the following layout. Go code lives at the root and in internal/, while the React frontend lives in frontend/.

myapp/

myapp/
├── main.go                  # Wails entry point
├── app.go                   # App struct with bound methods
├── wails.json               # Wails project configuration
├── go.mod
├── go.sum
├── internal/
│   ├── config/
│   │   └── config.go        # App configuration
│   ├── db/
│   │   └── db.go            # GORM database setup (SQLite)
│   ├── models/
│   │   ├── user.go          # User model + AutoMigrate
│   │   ├── blog.go          # Blog post model
│   │   └── contact.go       # Contact model
│   ├── services/
│   │   ├── auth.go          # Authentication service
│   │   ├── blog.go          # Blog CRUD service
│   │   └── contact.go       # Contact CRUD service
│   └── types/
│       └── types.go         # Shared request/response types
├── frontend/
│   ├── src/
│   │   ├── main.tsx          # React entry point (TanStack Router)
│   │   ├── routes/           # File-based routes (TanStack Router)
│   │   │   ├── __root.tsx    # Root route
│   │   │   ├── _layout.tsx   # Auth guard + sidebar layout
│   │   │   └── _layout/      # Protected page routes
│   │   ├── components/       # Reusable UI components
│   │   ├── hooks/            # TanStack Query hooks
│   │   └── lib/              # Utilities
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.js
└── cmd/
    └── studio/
        └── main.go           # GORM Studio standalone server

How File-Based Routing Works

Grit Desktop uses TanStack Router with file-based routing. Instead of a centralized route configuration, each page is a route file in routes/. The TanStack Router Vite plugin auto-discovers these files and generates a type-safe route tree.

File	URL	Purpose
routes/__root.tsx	(wrapper)	Root layout — wraps everything, renders Toaster
routes/login.tsx	/login	Login page (public)
routes/register.tsx	/register	Register page (public)
routes/_layout.tsx	(wrapper)	Auth guard + sidebar — no URL segment added
routes/_layout/index.tsx	/	Dashboard (protected)
routes/_layout/blogs.index.tsx	/blogs	Blog list page
routes/_layout/blogs.new.tsx	/blogs/new	Blog create form
routes/_layout/blogs.$id.edit.tsx	/blogs/:id/edit	Blog edit form

Key conventions:

1.The __root.tsx file is the topmost layout. It renders an Outlet where child routes appear.

2.Files prefixed with _ (like _layout.tsx) create pathless layouts — they wrap child routes without adding a URL segment.

3.Dot notation in filenames creates nested paths: blogs.index.tsx becomes /blogs, blogs.$id.edit.tsx becomes /blogs/:id/edit.

4.The $ prefix denotes dynamic parameters: $id in the filename becomes a typed route parameter accessible via Route.useParams().

5.Each route file exports a Route constant created with createFileRoute() — this registers the route and its component.

The route tree (routeTree.gen.ts) is auto-generated by the TanStack Router Vite plugin and gitignored. You never edit it manually. Just create or delete route files — the plugin handles the rest.

Start Development

Navigate into the project and start Wails in development mode. This launches the desktop window with hot-reload for both Go and React code.

Terminal

$cd myapp
$wails dev

Alternatively, if you prefer using the Grit CLI:

Terminal

$grit start

The app window opens automatically. Changes to Go files trigger a rebuild, and changes to React files trigger a Vite HMR refresh. The frontend dev server runs on http://localhost:34115 during development.

On first run, wails dev installs frontend dependencies automatically. Subsequent starts are much faster.

Open GORM Studio

GORM Studio provides a visual database browser. For desktop projects, it starts a standalone Gin server with the gorm-studio package mounted at /studio on port 8080 and automatically opens your browser.

Terminal

$grit studio

Your browser opens automatically at http://localhost:8080/studio where you can browse tables, inspect rows, and explore your SQLite database visually. This uses the same gorm-studio package as the web scaffold.

Development URLs

Desktop App

Native windowOpens automatically with wails dev

Frontend Dev

http://localhost:34115Vite dev server (also viewable in browser)

GORM Studio

http://localhost:8080/studioVisual database browser (grit studio)

Download Desktop Handbook (PDF)Complete offline reference for Grit Desktop development

Desktop Overview Resource Generation