Contacts: the mobile 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 — For the API.
• Node 20 or newer, with pnpm — The workspace, including apps/expo.
• Expo Go, or a simulator — Expo Go on your phone is the quickest. Xcode or Android Studio if you want a simulator.

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

1. Create the project

$grit new contacts --triple --expo --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 --expo --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 expo

Metro starts and prints a QR code. Scan it with Expo Go, or press i / a for a simulator. The API needs to be running too, from grit start server in another terminal.

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
$grit deploy --host user@server.com --domain contacts.example.com
# The app, built by Expo's service and submitted to the stores
$cd apps/expo
$npx eas build --platform all
$npx eas submit

A phone on your network cannot reach localhost, so set EXPO_PUBLIC_API_URL to the deployed API before building. During development, point it at your machine's LAN address rather than 127.0.0.1 for the same reason.

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.