Home › Next.js › Next.js AGENTS.md

Next.js AGENTS.md

AGENTS.md for Next.js 16 App Router projects: commands, folder layout, data access, auth, and done criteria.

AGENTS.mdNext.js

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Next.js app

## Commands
- `pnpm dev` · `pnpm build` · `pnpm lint` (`eslint .`) · `pnpm typecheck` (`tsc --noEmit`) · `pnpm test` (Vitest) · `pnpm e2e` (Playwright)

## Layout
- `app/` routes only (pages, layouts, `route.ts` handlers, `loading.tsx`, `error.tsx`).
- `components/ui/` primitives, `components/<feature>/` composites.
- `lib/server/` data access and services (import `server-only` at the top), `lib/` shared utils, `actions/` Server Actions.

## Rules
- Data is fetched in Server Components or route handlers through `lib/server/*` functions. Client Components receive data as props or call Server Actions; they never import DB clients.
- Every Server Action and route handler: validate input with zod, check auth (`await auth()` or the project's helper), check ownership, then act.
- Env vars validated in `lib/env.ts`; only `NEXT_PUBLIC_*` vars reach the browser.
- Use `next/link`, `next/image`, `next/font`; set metadata per route.
- Keep `"use client"` boundaries small; no `useEffect` data fetching for data the server can provide.
- Prefer existing components over new dependencies; ask before adding a UI kit or state library.

## Don't
- Don't disable TypeScript or ESLint errors in `next.config.ts`.
- Don't commit `.env*` files except `.env.example`.

## Done
Typecheck, lint, unit tests, and `pnpm build` pass; UI changes are checked in the browser.