Running grit new

The interactive prompts, the flags, and what each kit means.

7 mineasy

grit new is the command you'll run the most for the first month. This lesson covers what it does, what the prompts mean, and the flags that let you skip the prompts when you know what you want.

The simplest form

Terminal

$grit new my-first-grit

That creates a folder called my-first-grit/, prompts you for two choices (architecture mode + frontend framework), then generates a full project. The interactive flow is friendly — arrow keys, enter to confirm, escape to cancel.

The two prompts

1. Architecture

The first prompt asks which kit shape you want:

? Select architecture:
  > Triple — Web + Admin + API (Turborepo)         [the SaaS shape]
    Double — Web + API (Turborepo)                 [no admin panel]
    Single — Go API + embedded React SPA           [one binary]
    API Only — Go API (no frontend)                [headless backend]
    Mobile — Expo + Go API                         [shared types]

For this course, pick Triple. We cover every kit in chapter 5; for now Triple is the most representative — three apps, admin panel, the full experience.

2. Frontend framework

? Select frontend framework:
  > Next.js (App Router)        [SSR, marketing-friendly]
    Vite + TanStack Router      [pure SPA, faster dev]

Pick Next.js for now — easier to follow along.

Skipping prompts with flags

Once you know what you want, flags let you scaffold without interaction:

Terminal

$grit new my-app --triple --next       # Triple + Next.js
$grit new my-app --single --vite       # Single binary + Vite SPA
$grit new my-app --api                  # API-only
$grit new my-app --mobile               # Mobile + API
$grit new my-app --triple --desktop     # Triple + Wails desktop

What "Triple" produces

After the prompts, you'll see a printed checklist of what was created and how to start:

✓ Created my-first-grit/
  ✓ Wrote 84 files
  ✓ Initialized go module

  Next steps:
    cd my-first-grit
    docker compose up -d        # starts Postgres, Redis, MinIO
    pnpm install                # installs JS deps
    grit migrate                # runs DB migrations
    grit seed                   # seeds the admin user
    grit start                  # runs API + web + admin together

  URLs (once running):
    Web:    http://localhost:3000
    Admin:  http://localhost:3001
    API:    http://localhost:8080
    Studio: http://localhost:8080/studio   (DB browser)
    Mail:   http://localhost:8025          (Mailhog UI)

That checklist is your roadmap for the next two lessons. Don't worry about running anything yet — we'll go file-by-file first.

Naming rules

The project name has to be:

Lowercase letters, numbers, and dashes only
Start with a letter
Not collide with an existing directory

Good: invoice-tracker, order-pos, my-first-grit. Bad: My_App, 123-app, app with spaces.

Quick check

You want to scaffold a project called `field-pos` with the Triple kit + Vite frontend. What's the right command?

Try it

Scaffold a project called my-first-grit with the triple kit + Next.js frontend.

Then list what was created by running ls my-first-grit (Mac/Linux) or dir my-first-grit (Windows). Paste the output in notes.md.

What's next

You have a project on disk. The next lesson is the guided tour — we walk into apps/, packages/, the root config files, and you'll be able to explain every file to a teammate.

Spot a typo? Have an idea?

Help us improve this lesson. One click opens a GitHub issue with the lesson URL pre-filled — suggest clearer wording, report a bug, or request more depth. The course keeps improving thanks to learners like you.

Suggest an improvement on GitHub

Previous lesson Next lesson