# AGENTS.md — Next.js 15 (App Router) + TypeScript + Tailwind

## Project

TODO: One sentence describing what this app does.

## Stack

- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- React 19 (Server Components by default)
- Package manager: pnpm

## Commands

```bash
pnpm install        # install
pnpm dev            # dev server on http://localhost:3000
pnpm build          # production build (must pass before any PR)
pnpm lint           # ESLint
pnpm typecheck      # tsc --noEmit
pnpm test           # vitest
pnpm test -- path/to/file.test.ts   # single test
```

A change is not "done" until `pnpm build && pnpm typecheck && pnpm test` all pass.

## Directory layout

```
src/
  app/              # routes, layouts, route handlers (server-only by default)
  components/       # shared React components, PascalCase filenames
  lib/              # framework-agnostic helpers, no React, no `next/*` imports
  server/           # server-only modules (db, auth, secrets)
  styles/           # global Tailwind layer
public/             # static assets served at /
```

## Non-negotiables

- **Server Components by default.** Add `'use client'` only when you use state, effects, browser APIs, or event handlers.
- **No default exports** except for Next.js conventions (`page.tsx`, `layout.tsx`, `error.tsx`, `loading.tsx`, `route.ts`, `middleware.ts`).
- **No `any`.** Use `unknown` and narrow.
- **No `useEffect` for fetching.** Fetch in Server Components or Route Handlers.
- **No client-side env vars** unless prefixed `NEXT_PUBLIC_`. Validate all env vars at module load with Zod.
- **Throw on misconfigured env**, never silently default.
- **Tailwind only.** No CSS modules, no styled-components.
- **Server Actions** for mutations from forms; **Route Handlers** for public APIs.

## TypeScript style

- `interface` for object shapes that may be extended; `type` for unions / mapped types.
- Named exports always.
- Co-locate types with the code that uses them, unless shared (then `src/lib/types.ts`).

## React style

- Function components only.
- Props interface declared above component, named `<ComponentName>Props`.
- No prop spreading except into a single underlying primitive (`<button {...rest} />`).
- `cn()` (clsx + tailwind-merge) for conditional classes.

## Data fetching

- Server Components fetch directly with `fetch()` (Next caches by default) or db client in `src/server/`.
- Use `cache()` from `react` for request memoization.
- Use `unstable_cache()` for cross-request caching with explicit `revalidate` and `tags`.
- For mutations: Server Actions in `src/app/.../actions.ts`. Validate input with Zod. Call `revalidatePath` / `revalidateTag` after writes.

## Forbidden

- Do not install new npm packages without listing them and getting approval.
- Do not introduce a state library (Zustand, Redux, Jotai). Lift state or use URL state.
- Do not call client-side `fetch` to your own API routes from a page that could be a Server Component.
- Do not use `getServerSideProps` / `getStaticProps` (Pages Router only).
- Do not commit secrets. `.env.local` is gitignored — keep it that way.
- Do not run destructive commands without explicit instruction.

## When in doubt

- Prefer Server Components.
- Prefer fewer files.
- Prefer smaller diffs.
- Read the existing code before adding new patterns.