Your First Grit App

What is Grit?

Grit is a full-stack framework that combines Go (for the backend) with React (for the frontend).

• • Grit uses Go with the Gin web framework and GORM ORM for the API
• • Grit uses React with Next.js or TanStack Router for the frontend
• • Grit generates a complete project with authentication, admin panel, and more
• • Grit has a CLI (Command Line Interface) that helps you generate code, run migrations, and deploy
• • Grit is open source and free to use (MIT license)

Prerequisites

Before installing Grit, you need four tools on your computer:

Install Grit

Grit is installed using Go's go install command. This downloads the Grit CLI binary and puts it in your Go bin directory.

go install github.com/MUKE-coder/grit/v2/cmd/grit@latest

Command Explained

• • go install tells Go to download and compile a package
• • github.com/MUKE-coder/grit/v2/cmd/grit is the path to the Grit CLI on GitHub
• • @latest means get the newest version

After installation, verify it works:

grit version
# Output: grit version 3.5.0

Create Your First Project

The grit new command creates a new project. When you run it without flags, it enters interactive mode and asks you questions.

grit new myapp

Question 1: Choose your architecture

? Select architecture:
  > Triple — Web + Admin + API (Turborepo)
    Double — Web + API (Turborepo)
    Single — Go API + embedded React SPA (one binary)
    API Only — Go API (no frontend)
    Mobile — API + Expo (React Native)

For this course, select Triple. This gives you the full experience: a web app, an admin panel, and a Go API — all in one project.

Question 2: Choose your frontend

? Select frontend:
  > Next.js — SSR, SEO, App Router
    TanStack Router — Vite, fast builds, small bundle (SPA)

Select Next.js for this course.

Question 3: Choose your admin style

? Select admin panel style:
  > Default — Clean dark theme
    Modern — Gradient accents
    Minimal — Ultra clean
    Glass — Glassmorphism

Select Default. You can always change this later.

Understanding the Project Structure

Grit created a folder called myapp/. Let's look inside:

myapp/
├── apps/
│   ├── api/           ← Go backend (Gin + GORM)
│   ├── web/           ← Next.js frontend
│   └── admin/         ← Next.js admin panel
├── packages/
│   └── shared/        ← Zod schemas + TypeScript types
├── docker-compose.yml ← PostgreSQL, Redis, MinIO, Mailhog
├── turbo.json         ← Monorepo task runner config
├── package.json       ← Root package.json
├── pnpm-workspace.yaml ← Workspace definition
└── .env               ← Environment variables

Structure Explained

Inside the Go API

The Go API is the brain of your application. It lives in apps/api/:

apps/api/
├── cmd/
│   ├── server/main.go    ← Entry point (starts the API)
│   ├── migrate/main.go   ← Database migration runner
│   └── seed/main.go      ← Database seeder
└── internal/
    ├── config/            ← Reads .env variables
    ├── database/          ← Connects to PostgreSQL
    ├── models/            ← Database tables (User, Upload, Blog...)
    ├── handlers/          ← HTTP request handlers
    ├── services/          ← Business logic
    ├── middleware/         ← Auth, CORS, logging, rate limiting
    ├── routes/            ← Route definitions
    ├── cache/             ← Redis caching
    ├── storage/           ← File uploads (S3/MinIO)
    ├── mail/              ← Email service (Resend)
    ├── jobs/              ← Background jobs (asynq)
    ├── ai/                ← AI service (Vercel AI Gateway)
    └── totp/              ← Two-factor authentication

How a Request Flows Through the API

When a user does something (like clicking "Login"), here's what happens:

Browser → HTTP Request → Middleware → Handler → Service → Database
                            ↓                                 ↓
                      (Auth check)                      (GORM query)
                            ↓                                 ↓
                   Handler ← Service ← Database Response
                            ↓
                   JSON Response → Browser

• • Middleware runs first — checks if the user is logged in, logs the request, applies rate limits
• • Handler receives the request — validates input data, then calls the service
• • Service contains business logic — talks to the database, processes data, applies rules
• • Model defines the database table — what columns exist, their types, and relationships

Start Docker Services

Your app needs a database (PostgreSQL), cache (Redis), file storage (MinIO), and a mail catcher (Mailhog). All of these run inside Docker containers.

cd myapp
docker compose up -d

Command Explained

• • cd myapp — moves into your project folder
• • docker compose up — reads docker-compose.yml and starts all services
• • -d means "detached" — they run in the background so you get your terminal back

Check if everything is running:

docker compose ps
# All 4 services should show "running"

Start the Development Servers

Install JavaScript dependencies first:

pnpm install

Then start all apps at once:

pnpm dev

This starts three servers simultaneously using Turborepo:

Built-in Tools

Your API comes with five built-in tools, each with its own web interface:

The .env File

Every Grit project has a .env file at the root. This file stores all your configuration as key-value pairs:

# Core
APP_NAME=myapp
APP_ENV=development
APP_PORT=8080
DATABASE_URL=postgres://postgres:postgres@localhost:5432/myapp?sslmode=disable
JWT_SECRET=your-secret-key
REDIS_URL=redis://localhost:6379

# Storage (MinIO for local development)
STORAGE_DRIVER=minio
STORAGE_ENDPOINT=localhost:9000

# Email
RESEND_API_KEY=
MAIL_FROM=noreply@localhost

# AI (Vercel AI Gateway)
AI_GATEWAY_API_KEY=
AI_GATEWAY_MODEL=anthropic/claude-sonnet-4-6

Essential CLI Commands

Here are commands you'll use every day:

What You Learned

• What Grit is — a full-stack Go + React framework
• How to install Grit with go install
• How to scaffold a project with grit new (interactive and with flags)
• The monorepo project structure (apps/api, apps/web, apps/admin, packages/shared)
• How the Go API is organized (middleware → handler → service → database)
• How to start Docker services and development servers
• The 5 built-in tools (GORM Studio, API Docs, Pulse, Sentinel, Mailhog)
• How the .env file works and why you never commit it to Git