grit new: what lands, and the shape of a project

One command, and the answers to most of chapter twenty six are already in your directory. This chapter is a tour of what arrives, so that nothing in part five is a surprise.

Installing

curl -fsSL https://gritframework.dev/install.sh | sh    # macOS, Linux
# Windows PowerShell
irm https://gritframework.dev/install.ps1 | iex
go install github.com/MUKE-coder/grit/v3/cmd/grit@latest

grit version

Creating a project

grit new clinic

It asks a few questions, or you can answer them up front:

grit new clinic --api              # API only, no frontend
grit new clinic --architecture triple

The architecture decides how many frontends you get. It is a word this framework uses in a specific way, and it is worth pinning down now because it is not the same thing as an architecture style:

• triple
• Web app, admin panel and API, as three applications
• double
• Web app and API, with admin as role-protected routes in the web app
• single
• One binary serving an embedded SPA
• api
• The Go API alone
• mobile
• API plus an Expo application

What arrives

clinic/
├── grit.json                 the project's own description
├── docker-compose.yml        Postgres, Redis, MinIO, Mailhog
├── docker-compose.prod.yml
├── apps/
│   ├── api/                  the Go backend
│   ├── web/                  the public Next.js app
│   └── admin/                the admin panel
├── packages/
│   └── shared/               Zod schemas and TypeScript types
└── tests/

The Go side is where this book's attention goes:

apps/api/
├── go.mod
├── Dockerfile
├── cmd/
│   ├── server/               the API
│   ├── migrate/              schema changes
│   ├── seed/                 realistic data
│   ├── backup/               and
│   └── restore/              the half that matters
└── internal/                 about fifty packages

Five commands rather than one. cmd/restore existing beside cmd/backup is B5 from the last chapter answered honestly: a backup you have never restored is a rumour, so the restore is a first-class command rather than a runbook.

The internal packages

Around fifty, and the names tell you what has already been decided for you. Grouped by what they answer:

• Your layers
• models, services, handlers, routes, policies
• Identity
• authz, password, totp, access, crypto
• Data
• database, migrate, paginate, concurrency, money, ids
• Work
• jobs, cron, outbox, saga, workflow, events
• Outside
• storage, files, media, mail, sms, webhooks, safefetch
• Operations
• audit, appendonly, backup, health, tracing, flags
• Compliance
• erasure, gdpr-adjacent pieces, settings
• Delivery
• respond, sanitize, imports, export, pdf, realtime, sync

You will not read all of these. The point of listing them is that each one is a thing you did not write, and most of them correspond to a lettered problem from chapter twenty six.

Running it

cd clinic
grit migrate        # create the schema
grit seed           # realistic data to develop against
grit start          # everything, together

grit start brings up the API, the frontends and the infrastructure at once, which is D2 gone. What is now listening:

• :8080
• The Go API
• :3000
• The web app
• :3001
• The admin panel
• /studio
• A database browser: tables, queries, the ERD
• /docs
• The API reference, generated from the registered routes
• /pulse
• Latency, query counts, profiles
• /sentinel
• Errors, with the request attached

The second group is the interesting one. /studio is D6, /docs is D7 and/pulse is D5, and all three are paths that were already there rather than tools you installed.

grit.json, and the seeding that matters

grit.json records what the project is: its architecture, its module toggles, its name. The CLI reads it so that later commands know the shape of the thing they are editing.

The seed is worth insisting on, because it is the habit people skip:

grit seed Patient --count 50000

Fifty thousand rows is where you discover whether the list page works. At ten rows the sort is instant, pagination has one page, and an N+1 costs ten queries instead of ten thousand. That is D9, and the seeder is built as the pipeline from chapter fourteen: rows built in chunks, written in batches, with the number in flight bounded by a channel, so a million rows runs in about a minute with the heap flat.

Modules you can switch off

Eleven subsystems are toggles rather than permanent fixtures:

MODULE_AI=false
MODULE_AUDIT=false
MODULE_BACKUP=false
MODULE_CRON=false
MODULE_FILES=false
MODULE_FLAGS=false
MODULE_JOBS=false
MODULE_MAIL=false
MODULE_REALTIME=false
MODULE_TWOFACTOR=false
MODULE_WEBHOOKS=false

Set one to false in .env and that subsystem does not start. Delete its package and the rest still builds. This is the "batteries included, individually removable" claim, and it is checkable: the packages are separate and the seams are real.

It is still just Go

Open apps/api/internal/services/user.go. It is a struct with a *gorm.DBfield and methods on it. Open a handler: it reads a request, calls one service method and writes a response. There is no framework type in your code and nothing to learn before you can read it.

// The shape of every generated service.
type ContactService struct {
    DB *gorm.DB
}

That is the whole dependency. If Grit disappeared tonight, this project compiles tomorrow, because there is nothing of Grit inside it. Everything you learned in parts one to three applies directly, which was the reason for putting those parts first.

grit new bookshop --api
cd bookshop
grit migrate
grit seed
grit start

Assignment

Commit your work with the message Grit New - Assignment One, exactly as written, so the leaderboard can score it.

grit new fieldbook

git -C fieldbook ls-files | wc -l