Next.js App Router + TypeScript Rules

# CLAUDE.md — Next.js App Router + TypeScript

## Routing & rendering

- App Router only. Do not create files under `pages/`.
- Server Components by default. Add `'use client'` only when you need state, refs, browser APIs, or event handlers.
- Co-locate route segments under `app/`. Route handlers go in `route.ts`, pages in `page.tsx`, layouts in `layout.tsx`.
- Use `loading.tsx`, `error.tsx`, and `not-found.tsx` for built-in boundaries — don't roll your own when the file convention exists.
- Default to streaming with `<Suspense>` instead of blocking the entire route on slow data.

## Data fetching

- Fetch in Server Components with `async/await`. Pass data down as props; don't refetch the same data on the client.
- Use Server Actions for mutations. Return typed results — never throw raw errors back to the client.
- Cache deliberately: choose between `force-cache`, `no-store`, or `revalidate: N` per `fetch` call. Don't leave it implicit.
- Tag cache reads (`next: { tags: ['user-list'] }`) and invalidate them with `revalidateTag` after mutations.

## TypeScript

- `strict: true` in `tsconfig.json`. No `any`, no `as` casts unless they're narrowing a `unknown`.
- Type the `params` and `searchParams` of every page and layout — these are `Promise`s in current Next.
- Validate every untrusted input (form data, search params, route handler bodies) with Zod before using it.

## Styling & UI

- Tailwind for layout and spacing. No CSS-in-JS for static styles.
- Keep one global stylesheet (`app/globals.css`) — no per-component CSS files.
- Images: always use `next/image` with explicit width/height or `fill` + a sized parent.

## SEO

- Export `metadata` (or `generateMetadata`) from every page. Set `title`, `description`, and `alternates.canonical`.
- Generate sitemaps in `app/sitemap.ts` from your data sources, not by hand.
- Use `app/[route]/opengraph-image.tsx` to ship per-page OG images, not a single shared one.

## Don't

- Don't use `getServerSideProps`, `getStaticProps`, or `getInitialProps` — they don't exist in App Router.
- Don't import server-only modules (`fs`, `db client`, etc.) into client components.
- Don't disable TypeScript or ESLint errors to ship.
- Don't use `useEffect` to fetch data you could fetch on the server.