Contacts: the web 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 — The API is a Go module. go version to check.
• Node 20 or newer, with pnpm — The two frontends are a pnpm workspace. corepack enable pnpm if you have none.

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

1. Create the project

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

One command brings up all three, each line of output prefixed with the app it came from. Ctrl+C stops them together.

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

# A server you have SSH access to: systemd, Caddy, TLS
$grit deploy --host user@server.com --domain contacts.example.com
# Or Railway, which takes the variables from .env and gives you a URL
$grit deploy --railway

The first form builds the API, uploads it over SSH, writes a systemd unit and puts Caddy in front of it with a certificate. The two frontends are Next.js apps and deploy like any other: pnpm build and your host of choice, with NEXT_PUBLIC_API_URL pointed at the API you just deployed.

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.