Next.js example
AGENTS.md Template for Next.js
Copy an AGENTS.md example for Next.js App Router projects covering server and client components, routes, environment variables, tests, linting, and builds.
Use this as a verified starting point for a modern Next.js repository, then replace commands and paths with those actually present in the project.
Full version
Copy the AGENTS.md template
Replace every bracketed value and delete any rule you cannot verify in the repository.
# Next.js Repository Instructions
## Stack
- Framework: Next.js App Router
- Language: TypeScript
- Package manager: npm
- Styling: `[project choice]`
- Tests: `[Vitest/Jest]` and `[Playwright/other]`
## Commands
- Install: `npm ci`
- Develop: `npm run dev`
- Lint: `npm run lint`
- Type-check: `npm run typecheck`
- Unit tests: `npm test`
- End-to-end tests: `npm run test:e2e`
- Production build: `npm run build`
## Project Map
- `app/`: routes, layouts, loading and error boundaries
- `components/`: reusable UI
- `lib/`: server-safe domain utilities and integrations
- `public/`: static assets
- `tests/`: integration and end-to-end coverage
## Next.js Rules
- Prefer Server Components. Use `"use client"` only for state, effects, event handlers, or browser APIs.
- Never import server-only modules, database clients, or private environment variables into Client Components.
- Keep route-specific code near its route; promote code only after real reuse appears.
- Validate all untrusted route, form, header, cookie, and external API input.
- Provide meaningful loading, empty, error, and not-found behavior for user-facing routes.
- Preserve caching and revalidation semantics unless the task explicitly changes them.
## Testing and Handoff
- Add a focused test for changed behavior and at least one relevant failure path.
- For UI changes, verify the affected route at mobile and desktop widths.
- Run lint, type-check, focused tests, and `npm run build`.
- Report any command omitted because the corresponding script does not exist.Do not copy blindly: Do not retain App Router, Vitest, or Playwright rules if the repository uses the Pages Router or different test tools.
Minimal version
Start smaller when the repository is simple
# Next.js Repository Instructions
## Commands
- Develop: `npm run dev`
- Lint: `npm run lint`
- Test: `npm test`
- Build: `npm run build`
## Rules
- Prefer Server Components; add `"use client"` only where browser state or APIs require it.
- Keep secrets and server-only code out of client bundles.
- Validate route inputs and handle loading, empty, and error states.
- Run lint, relevant tests, and a production build before handoff.Customize each field
Stack
Replace every bracketed value and remove tools not installed in package.json.
Server/client boundary
Keep this only for App Router projects; Pages Router repositories need different guidance.
Caching
Document project-specific fetch, revalidation, and dynamic-rendering rules if they are easy to regress.
UI verification
Name the actual browser or screenshot command if the repository has one.
Validate the instructions
- Compare every command against package.json and CI.
- Confirm `app/` exists before keeping App Router rules.
- Run the production build because it catches server/client boundary and route-generation failures missed in development.
- Test a route with a loading or error state, not only the happy path.
- Add nested instructions only for independently owned apps or packages.
Common mistakes
Assuming every component should be client-side
Default to Server Components and document the concrete browser capability that requires a client boundary.
Inventing scripts
Delete or replace any command missing from package.json.
Ignoring production builds
Require `npm run build` for changes that affect routes, rendering, or environment access.
Interactive tool
Generate a repository-specific starting file.
Choose your framework, real commands, paths, and approval boundaries, then copy or download the result.
Open AGENTS.md GeneratorRelated templates
Choose the closest repository shape.
Official sources
Instruction discovery and scope behavior were checked on August 13, 2026. Recheck product documentation when standardizing these files across a team.