Tech & AI, Explained

start-new-nextjs-project

6 min read

How to start a new Next.js project (with the playbook)

Status: 🟩 COMPLETE Last updated: 2026-06-19 Plain-English tagline: The full bootstrap procedure: from npx create-next-app to first commit, first deploy, and the project hygiene basics. ~45 minutes.

Goal

A fresh Next.js project that:

  • Uses TypeScript, App Router, Tailwind, shadcn/ui-ready
  • Is in a Git repo, on GitHub
  • Is deployed to Vercel at a .vercel.app URL
  • Has AGENT_GUIDE.md, PROGRESS.md, and a CLAUDE.md from the first commit
  • Is connected to a Supabase project (if you need a backend)

This is the procedure recommended by the playbook for any new webapp.

Prerequisites

  • Node.js 22+ (current LTS as of June 2026)
  • Git installed and configured (git config --global user.name and user.email)
  • GitHub account
  • Vercel account linked to GitHub
  • Supabase account (only if you need a backend)
  • A name for the project

Steps

1. Confirm the stack with the playbook

Before scaffolding, the playbook recommends:

  • Framework: Next.js (App Router)
  • Language: TypeScript
  • Styling: Tailwind CSS + shadcn/ui
  • Backend: Supabase (if backend needed) — pinned to same region as Vercel
  • Hosting: Vercel
  • Linting: ESLint (built into create-next-app)
  • Version control: Git + GitHub

Surface any area where you’d deviate (e.g. a different DB if your needs are unusual). For a typical webapp, the playbook defaults are right.

2. Scaffold the project

cd C:\Users\georg
npx create-next-app@latest my-project

Prompts (recommended answers in bold):

  • ✔ Would you like to use TypeScript? → Yes
  • ✔ Would you like to use ESLint? → Yes
  • ✔ Would you like to use Tailwind CSS? → Yes
  • ✔ Would you like your code inside a src/ directory? → No (keeps app/ at root for simpler imports)
  • ✔ Would you like to use App Router? → Yes
  • ✔ Would you like to use Turbopack for next dev? → Yes
  • ✔ Would you like to customize the import alias (@/* by default)? → No

The scaffold runs for ~30 seconds.

cd my-project

3. Verify the dev server runs

npm run dev

Open http://localhost:3000. See the default Next.js page. Kill the server (Ctrl+C).

4. Verify the production build runs

This is the playbook’s non-negotiable check.

npm run build

Should complete without errors. If it errors here on a fresh scaffold, something’s wrong with your Node/npm install.

5. Add the playbook files

Create three files at the project root:

CLAUDE.md

# {Project Name} — Claude Code Instructions
 
## Stack
- Next.js 16 (App Router) + TypeScript
- Tailwind CSS + shadcn/ui
- Supabase (Postgres + Auth + Storage) — region: {your region}
- Vercel hosting — functions pinned to {region}
 
## Standing rules
- Always run `npm run build` before pushing to main
- Never expose service_role keys to client code or NEXT_PUBLIC_* env vars
- Update PROGRESS.md when shipping a meaningful feature
 
## Where things live
- Routes: `app/**/page.tsx`
- Components: `components/**`
- Helpers: `lib/**`
- See AGENT_GUIDE.md for the full map

AGENT_GUIDE.md

# Agent Guide — {Project Name}
 
A map of the project for any AI agent (or human) working on it.
 
## Routes
| Route | File |
|---|---|
| `/` | `app/page.tsx` |
 
## Components
- (none yet)
 
## Database tables
- (none yet)
 
## Critical files
- `lib/supabase-client.ts` — browser-side Supabase client
- `lib/supabase-server.ts` — server-side Supabase client
- `middleware.ts` — session refresh
 
## Environment variables
- `NEXT_PUBLIC_SUPABASE_URL`
- `NEXT_PUBLIC_SUPABASE_ANON_KEY`
- `SUPABASE_SERVICE_ROLE_KEY` (server only)
 
## Common operations
- `npm run dev` — dev server
- `npm run build` — production build
- `npm run lint` — linter

PROGRESS.md

# Progress — {Project Name}
 
Reverse-chronological log of shipped work. Newest at top.
 
## 2026-06-19 — Project scaffolded
- Created with create-next-app (TypeScript, App Router, Tailwind, ESLint)
- Initial commit
- Pushed to GitHub
- Connected to Vercel
- First deploy successful at {url}

6. Initialize Git

Next.js auto-initializes a Git repo, but verify:

git status
# Should show all your files

If not a repo:

git init
git add .
git commit -m "Initial commit: Next.js scaffold + playbook files"

7. Create the GitHub repo

gh repo create my-project --private --source=. --remote=origin
git branch -M main
git push -u origin main

(Or use the web UI: create empty repo, follow GitHub’s “push existing” instructions.)

8. Deploy to Vercel

  1. Go to vercel.com/new.
  2. Import your GitHub repo.
  3. Framework should auto-detect as Next.js. Defaults are correct.
  4. Click Deploy. Wait ~90 seconds.
  5. Live URL: my-project.vercel.app.

9. Pin Vercel function region (if needed)

If you’ll have a Supabase backend in a specific region, pin Vercel functions to match:

Create vercel.json at the project root:

{
  "regions": ["syd1"]
}

(Replace with your region. See Vercel for region codes.)

Commit and push. Next deploy uses the pin.

10. If you need a backend: set up Supabase

See How-to: Set up Supabase.

In Vercel Settings → Environment Variables, add:

  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_ROLE_KEY

Redeploy.

npx shadcn@latest init

Choose your style preferences. shadcn/ui scaffolds components/ui/ and a few utilities. Add components on demand:

npx shadcn@latest add button
npx shadcn@latest add card

12. Wire up dark mode (optional)

See How-to: Set up dark mode. Even if you defer it, decide now (it’s much easier early than late).

13. Set up Claude Code memory

If this is a project Claude Code will help with often, consider:

  • Adding a project-specific memory file: ~/.claude/.../memory/project_{slug}.md
  • Pointing it from MEMORY.md
  • Saving the Live URL, GitHub repo, local path, hosting region as facts

This makes Claude productive from the next session forward.

14. Commit and push everything

git add .
git commit -m "Add playbook files, Vercel region pin, shadcn/ui"
git push

Verification

  • ✅ npm run dev works
  • ✅ npm run build succeeds
  • ✅ Site is live at your-project.vercel.app
  • ✅ Git repo on GitHub
  • ✅ Vercel auto-deploys on push
  • ✅ CLAUDE.md, AGENT_GUIDE.md, PROGRESS.md committed

What you’ve just built

A new Next.js project with:

  • Production stack (TypeScript, Tailwind, App Router, Turbopack)
  • Hosted, deployed, on a real URL
  • Version control + CI/CD via git push
  • Region pinning ready for low latency
  • Project hygiene files (AGENT_GUIDE, PROGRESS, CLAUDE.md) from day 1
  • Optional: shadcn/ui scaffolded, dark mode ready, Supabase wired up

You can start building features immediately. The next Claude Code session can ground itself in CLAUDE.md and AGENT_GUIDE.md with no re-onboarding.

See also

Sources

Graph View

Backlinks