1# CLAUDE.md — Next.js 15 App Router
2
3## Project overview
4<!-- One-sentence description of what this app does -->
5
6## Tech stack
7- **Framework**: Next.js 15 (App Router)
8- **Language**: TypeScript (strict mode)
9- **Styling**: Tailwind CSS v4
10- **Database**: PostgreSQL via Prisma ORM
11- **Auth**: NextAuth v5 (next-auth@beta)
12- **Package manager**: npm
13
14## Development commands
15```bash
16npm run dev        # start dev server on :3000
17npm run build      # production build
18npm run lint       # ESLint
19npx prisma studio  # open Prisma Studio
20npx prisma db push # push schema changes (dev only)
21npx prisma migrate dev --name <name>  # create a migration
22```
23
24## Project structure
25```
26app/                 # Next.js App Router pages & layouts
27  (auth)/            # auth-gated routes
28  api/               # API route handlers
29components/          # shared React components
30lib/
31  db.ts              # Prisma singleton
32  utils.ts           # shared helpers
33  queries.ts         # all DB queries
34prisma/
35  schema.prisma      # data model
36  seed.ts            # seed script
37auth.ts              # NextAuth root config
38middleware.ts        # route protection
39```
40
41## Coding conventions
42- Use **server components** by default; add `"use client"` only when needed
43- All DB access must go through `lib/queries.ts` — no raw Prisma in components
44- API routes live in `app/api/` and return `NextResponse.json()`
45- Environment variables: access via `process.env.VAR_NAME` (never import dotenv in app code)
46- Use the `cn()` helper from `lib/utils.ts` for conditional Tailwind classes
47- Prefer named exports; default export only for page/layout components
48
49## Environment variables
50```
51DATABASE_URL=
52NEXTAUTH_SECRET=
53GITHUB_ID=
54GITHUB_SECRET=
55NEXTAUTH_URL=http://localhost:3000
56```
57
58## Common pitfalls
59- Do NOT use `export const dynamic = "force-dynamic"` unless you've confirmed the route actually needs it
60- Server Actions must be in files with `"use server"` at the top or inline in server components
61- Prisma client must be imported from `@/lib/db`, not instantiated directly
62- When adding a new Prisma model, run `prisma migrate dev` — never edit the DB directly
63