# {{project_name}}

{{project_purpose}}

Next.js (App Router) with TypeScript. Package manager: {{pm}}.

## Commands

- Dev server: `{{pm}} run dev`
- Build: `{{pm}} run build`
- Lint: `{{pm}} run lint`
- Typecheck: `npx tsc --noEmit`
- Tests: `{{test_command}}`

Before finishing a task: typecheck, lint, and run tests related to the change. Run `{{pm}} run build` when you changed routing, config, or server/client boundaries.

## Project layout

- `app/`: routes, layouts, loading and error boundaries. Route-only components live next to their route.
- Shared UI components, server-only code and utilities live where the project already keeps them. Follow the existing folders; do not create new top-level folders without asking.
- Check `package.json` for the installed Next.js and React versions before using version-specific APIs.

## Server and client components

- Components are Server Components by default. Add `"use client"` only to the smallest component that needs state, effects, event handlers or browser APIs.
- Do not add `"use client"` to layouts or pages to make a child work; extract the interactive part instead.
- Pass serializable props from server to client components only (no functions, class instances or Dates unless the project handles them).
- Code that reads secrets or the database must never be imported by a client component. Mark such modules with `import "server-only"` if the project uses that package.

## Data fetching and caching

- Fetch data in Server Components, Route Handlers or Server Actions, not in `useEffect`, unless the data is user-interactive and client-only.
- Start independent requests together with `Promise.all`; do not `await` them one after another.
- Caching defaults have changed between Next.js versions (for example, `fetch` is not cached by default from Next.js 15). Check the installed version and set caching explicitly (`cache`, `next.revalidate`, route segment config) instead of relying on defaults.
- After a mutation, revalidate the affected paths or tags (`revalidatePath`, `revalidateTag`).

## Server Actions and Route Handlers

- Treat every Server Action and Route Handler as a public endpoint.
- Validate all input with {{validation_lib}} at the top of the action or handler.
- Check authentication and authorization inside the action using `{{auth_helper}}`. Middleware alone is not enough.
- Never trust IDs, prices, roles or ownership fields from the client. Look them up on the server.
- Return typed results with user-safe error messages. Do not return stack traces or internal errors.

## Environment variables

- Only variables prefixed `NEXT_PUBLIC_` are exposed to the browser. Never give a secret that prefix.
- When adding a variable, add it to `.env.example` with a placeholder and a comment, and tell me.

## Styling and UI

- Follow the existing styling approach. Do not introduce a new CSS framework or component library.
- Use `next/image` for images and `next/link` for internal links.
- Interactive elements must be keyboard accessible and have accessible names.

## Do not do without asking

- Add, remove or upgrade dependencies.
- Change `next.config.*`, `middleware.ts`, `tsconfig.json`, ESLint config or CI files.
- Delete or rename routes (URLs may be linked externally).
- Run database migrations or scripts against non-local environments.