Neexo Next.js Conventions

## Overview

Neexo projects default to Next.js 16 App Router patterns, server components, narrow TypeScript boundaries, and existing local UI conventions.

## Agent-first (Next.js 16+)

Before relying on training data for Next.js APIs:

1. Prefer version-matched docs bundled with the installed package: `node_modules/next/dist/docs/`
2. Keep any Next.js-managed blocks in root `AGENTS.md` / `CLAUDE.md` intact; put project rules outside those markers
3. When a Next.js 16+ dev server is running, use Next DevTools MCP (see the `next-devtools-mcp` tool entry) for live errors, routes, and logs instead of guessing from static HTML
4. Prefer Context7 or bundled docs over outdated Next 13/14 patterns from memory

## Server vs Client Components

- Prefer server components unless hooks, browser APIs, or event handlers require client components
- Keep server/client boundaries explicit — mark client components with `"use client"` at the top
- Use server actions for mutations; do not create API routes for simple form submissions

## Next.js 16 Specifics

- `params` and `searchParams` are now async in route components — always `await` them:
  ```tsx
  export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
    const { slug } = await params
  }
  ```
- `cookies()` and `headers()` from `next/headers` are async — `await` before reading
- Turbopack is the default bundler in development — do not add Webpack-specific config unless required for production
- Use the `use` hook from React 19 to unwrap promises in client components
- Use `"use cache"` for fine-grained caching instead of relying solely on route segment config

## TypeScript and Code Style

- Avoid `any` unless justified at an integration boundary
- Reuse existing components, hooks, utilities, and design tokens
- Add dependencies only when the existing stack cannot reasonably solve the problem
- Prefer `satisfies` for type narrowing of config objects

## Patterns to Avoid

- Do not use `getServerSideProps` or `getStaticProps` — these are Pages Router patterns
- Do not wrap server components in unnecessary client wrappers
- Do not use `useEffect` for data fetching — fetch in server components or use server actions
- Do not invent Next.js APIs from older training data when bundled docs disagree