Contacts: the desktop app

The app is a contact book: contacts that belong to groups, each with a photo. Two resources, two commands, and everything that follows is the same in every tier. What differs is what you run and where it ends up, which is what this page is about.

Before you start

• Go 1.21 or newer — Both the API and the desktop shell are Go.
• Node 20 or newer, with pnpm — The frontends, including the desktop app's own.
• The Wails CLI — Install from wails.io. grit start desktop says so plainly if it is missing, rather than failing obscurely.

And Grit itself: go install github.com/MUKE-coder/grit/v3/cmd/grit@latest.

1. Create the project

$grit new contacts --triple --desktop --theme emerald --db sqlite
$cd contacts

Postgres is the default. --db sqlite above means the project runs with no database server at all, which is the shortest path to seeing it work; drop the flag when you want Postgres, and docker compose up -d brings one up along with Redis, MinIO and a mail catcher.

Next.js or TanStack

The command above builds the frontend with Next.js. The same tier with TanStack Router and Vite instead is one flag:

$grit new contacts --triple --desktop --vite --theme emerald --db sqlite

Everything after this point is identical. The resources, the API, the admin screens and the deployment are the same; what changes is the router and the build tool, and the admin panel is written in whichever dialect that app speaks.

Pick a theme

--theme sets the sign-in layout, the dashboard tokens, the fonts and the brand colours, and it applies to both frontends. Eight ship with Grit:

Nothing is baked in. THEME and VITE_THEME in .env both carry the name, so changing it there repaints the app without re-scaffolding.

2. Describe the data

A group first, because a contact points at one. Each command writes the Go model, the migration, the service, the handler, the routes, the Zod schema, the TypeScript types and an admin screen, and registers all of it.

$grit generate resource Group \
$  --fields "name:string,description:text"

Then the contact, with a photo and a group to belong to. The belongs_to:Group field is what makes the admin screen render a picker rather than a text box asking for an id.

$grit generate resource Contact \
$  --fields "name:string,email:email,phone:tel,photo:file:image,group:belongs_to:Group"

3. Build the database

$grit migrate
$grit seed

grit migrate creates the tables from the models, and grit seed fills them: an administrator you can sign in as, a few users, and an API key. The administrator is admin@example.com with the password admin123. Change it before anybody else can reach the machine.

4. Run it

$grit start desktop

Wails opens a native window with hot reload. Run grit start in another terminal for the API it talks to, or grit start on its own brings up the desktop app too when the toolchain is installed.

5. What you have

Two resources, and for each of them: a table with sorting, filtering, search, pagination, bulk edit and CSV import and export; a form that validates on both sides from one schema; and REST endpoints under /api/v1/groups and /api/v1/contacts with the same rules applied.

The photo field is a real upload: the browser asks the API for a presigned URL and sends the file straight to storage, so the file never passes through the API process. With STORAGE_DRIVER=local that storage is a directory on disk, which is the default when there is no MinIO to talk to.

6. Deploy it

# The API, as in every other tier
$grit deploy --host user@server.com --domain contacts.example.com
# The desktop app is a file people install
$cd apps/desktop && wails build

Deployment splits in two here. The API goes to a server like any other; the desktop application is an artefact you distribute. wails build produces a binary for the platform you build on, so a release for three platforms means building on three, or in CI. Point it at the deployed API by setting VITE_API_URL before you build, or it will look for localhost on a stranger's machine.

Before any of that, read the go-live checklist: it is the list of things that are fine in development and not in production, starting with the seeded password above and the secrets in .env.