Raw view: Next.js App Router CLAUDE.md

No invisible, zero-width, or bidi-control characters detected.

# {{PROJECT_NAME}}

Next.js App Router (16.x) + TypeScript (strict) + Tailwind CSS v4 + {{ORM}} on {{DB_NAME}}. Package manager is **pnpm**; never run `npm` or `yarn`. Node {{NODE_VERSION}} (see `.nvmrc`).

## Commands

| Task | Command |
|------|---------|
| Install | `pnpm install --frozen-lockfile` |
| Dev server | `pnpm dev` (http://localhost:3000) |
| Typecheck | `pnpm exec tsc --noEmit` |
| Lint | `pnpm lint` (runs `eslint .`; `next lint` was removed in Next 16) |
| Unit tests | `pnpm vitest run` (single file: `pnpm vitest run src/lib/foo.test.ts`) |
| E2E | `pnpm playwright test` (needs `pnpm build` first or a running `pnpm dev`) |
| Build | `pnpm build` |
| DB (Drizzle) | `pnpm drizzle-kit generate` then `pnpm drizzle-kit migrate`; inspect with `pnpm drizzle-kit studio` |
| DB (Prisma) | `pnpm prisma migrate dev --name <change>`; regenerate client with `pnpm prisma generate` |

Definition of done: typecheck, lint, and `pnpm vitest run` exit 0. Also run `pnpm build` when you touched routing, `next.config.*`, or anything under `app/`.

## Layout

- `app/` holds routes only: `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts`. No business logic in `app/`.
- `src/components/` UI. `src/lib/` pure logic and data access. `src/db/` schema and client. `src/env.ts` validated env.
- Colocate tests as `*.test.ts(x)` next to the source. Playwright specs live in `e2e/`.

## Server vs client components

- Every file is a Server Component unless its first line is `'use client'`. Add the directive only to leaf components that need state, effects, refs, or browser APIs.
- Never import `src/db/*` or anything that reads a secret from a `'use client'` file. Put `import 'server-only'` at the top of server-only modules so the bundler fails loudly.
- Pass data down from server components as props; do not fetch in client components when the parent server component can.
- `params` and `searchParams` are Promises: `const { id } = await params;`. `cookies()`, `headers()`, and `draftMode()` are also async.
- Mutations go through Server Actions (`'use server'` files in `src/actions/`). Validate input with `zod` inside the action; never trust the FormData shape.

## Route handlers

- `app/api/<name>/route.ts` exports named `GET`, `POST`, etc. Use `NextRequest`/`NextResponse`. Return `NextResponse.json(body, { status })` with an explicit status on every error path.
- Route handlers are for webhooks and non-React clients. For form submissions from our own UI, use a Server Action instead.
- Request-path logic lives in `proxy.ts` at the project root (Next 16 name for `middleware.ts`). Keep it to redirects and header checks; it runs on every matched request.

## Environment variables

- All env access goes through `src/env.ts`, which parses `process.env` with `zod` and exports a typed object. Do not read `process.env.X` anywhere else.
- Only `NEXT_PUBLIC_*` variables reach the browser. Never prefix a secret with `NEXT_PUBLIC_`.
- `.env.example` lists every variable with a dummy value. Add a line there when you add a variable. Never commit `.env.local`.

## Data layer

- Schema changes: edit the schema file, generate a migration, commit both. Never hand-edit a generated migration or the `drizzle/meta` snapshots.
- Queries live in `src/lib/queries/*.ts` and return plain objects, not ORM instances, so they can cross the server/client boundary.
- Wrap multi-statement writes in a transaction.

## Testing

- Vitest with `environment: 'jsdom'` for components, `node` for lib. Use `@testing-library/react`; query by role, not test id, unless there is no accessible role.
- Mock the database at the query-function boundary (`vi.mock('@/lib/queries/users')`), not the ORM client.
- Playwright: one spec per user flow, `test.describe` per page. Use `page.getByRole`. Do not add `page.waitForTimeout`.

## Do not

- Do not add `'use client'` to a layout or page to fix a hooks error; move the hook into a child component.
- Do not use `// @ts-ignore`; use `// @ts-expect-error` with a reason, or fix the type.
- Do not edit `next-env.d.ts`, `.next/`, or `pnpm-lock.yaml` by hand.
- Do not run `pnpm drizzle-kit push` or `prisma db push` against anything but a local database.