Next.js App

# Next.js App Router Development

## Project Overview

This is a Next.js application using the App Router architecture with TypeScript and React Server Components.

## Setup Commands

- Install dependencies: `npm install` or `pnpm install`
- Start dev server: `npm run dev` or `pnpm dev`
- Build for production: `npm run build` or `pnpm build`
- Run production server: `npm start` or `pnpm start`
- Run linter: `npm run lint` or `pnpm lint`

## Code Style

- Use TypeScript strict mode for all files
- Prefer Server Components by default; only add `"use client"` when necessary
- Use functional components with hooks
- Follow Next.js file-based routing conventions
- Use the `app/` directory structure (not `pages/`)
- Organize components in feature-based folders

## Server vs Client Components

- Server Components (default): Use for data fetching, static content, and server-side logic
- Client Components (`"use client"`): Required for useState, useEffect, event handlers, browser APIs
- Keep client components small and focused
- Pass serializable data from Server to Client Components

## Routing Conventions

- `app/page.tsx` - Root page
- `app/about/page.tsx` - /about route
- `app/layout.tsx` - Root layout
- `app/[slug]/page.tsx` - Dynamic route
- `app/api/route.ts` - API route handler
- Use `generateStaticParams` for static generation with dynamic routes

## Data Fetching

- Use async/await in Server Components for data fetching
- Leverage Next.js fetch caching automatically
- Use `revalidate` option for ISR (Incremental Static Regeneration)
- For client-side fetching, use SWR or React Query

## Testing Instructions

- Run unit tests: `npm test` or `pnpm test`
- Run E2E tests: `npm run test:e2e` (if configured)
- Check TypeScript: `npx tsc --noEmit`
- Run all checks before committing

## Common Gotchas

- Images: Use `next/image` component for optimization
- Links: Use `next/link` for client-side navigation
- Metadata: Export `metadata` object from pages and layouts
- Loading states: Create `loading.tsx` files for automatic loading UI
- Error handling: Create `error.tsx` files for error boundaries

## Environment Variables

- Use `.env.local` for local development secrets
- Prefix client-side vars with `NEXT_PUBLIC_`
- Never commit `.env.local` to git

## PR Instructions

- Ensure `npm run build` completes without errors
- Run `npm run lint` and fix all warnings
- Test the production build locally before pushing
- Update documentation if adding new environment variables or routes