Next.js App Router

Scenario

You are working on a Next.js application using the App Router.

The project uses:

• Next.js
• TypeScript
• React
• Tailwind CSS
• pnpm
• Vitest

The team wants coding agents to follow the existing App Router architecture instead of introducing inconsistent patterns.

In particular, the agent should understand:

• where routes belong;
• when client components are appropriate;
• where reusable components belong;
• where server-side logic belongs;
• what validation should run after changes.

Repository Structure

web-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── dashboard/
│   │   │   └── page.tsx
│   │   └── api/
│   │       └── users/
│   │           └── route.ts
│   ├── components/
│   │   ├── ui/
│   │   └── dashboard/
│   └── lib/
│       ├── auth.ts
│       └── users.ts
├── tests/
├── package.json
└── AGENTS.md

AGENTS.md

# Project Instructions

## Package Management

- Use `pnpm`.
- Do not create npm or Yarn lockfiles.

## Next.js Architecture

- Use the App Router under `src/app`.
- Add pages and layouts within the appropriate route segment.
- Keep reusable React components outside route folders under `src/components`.
- Keep shared server-side utilities under `src/lib`.

## Server and Client Components

- Prefer Server Components unless browser APIs, client-side state, effects, or event handlers require a Client Component.
- Add `"use client"` only to components that require client-side execution.
- Do not convert an existing Server Component to a Client Component only to simplify an implementation.

## API Routes

- Place HTTP route handlers under `src/app/api`.
- Keep substantial business logic outside route handlers.
- Route handlers should validate the request, call the appropriate application logic, and construct the HTTP response.

## Testing

- Add or update tests when behavior changes.
- Run the tests relevant to the changed area.

## Validation

Before completing a task, run:

- `pnpm lint`
- `pnpm typecheck`
- `pnpm test`

What This Does

This AGENTS.md establishes architectural boundaries for a Next.js App Router project.

It tells the coding agent that the repository intentionally separates:

Routing              → src/app
Reusable components  → src/components
Shared server logic  → src/lib
HTTP endpoints        → src/app/api

It also gives the agent guidance about Server and Client Components.

That matters because adding "use client" can change where a component executes and what it can safely access.

The instruction does not prohibit Client Components. It establishes the project's default:

Prefer server execution unless client execution is actually required.

What This Does NOT Do

The file does not attempt to reproduce the Next.js documentation.

For example, it does not explain:

• how React rendering works;
• every App Router convention;
• every supported Next.js API;
• how Tailwind classes work;
• basic TypeScript syntax.

It also does not force every piece of business logic into one specific file.

An instruction such as:

- Put all business logic in `src/lib/services.ts`.

would probably be unnecessarily restrictive unless that is genuinely how the repository is organized.

Why These Instructions Matter

Framework conventions alone are not always enough to describe how a particular team uses a framework.

Consider this route:

export async function POST(request: Request) {
  const body = await request.json();

  // validation
  // database queries
  // business rules
  // third-party API call
  // response formatting
}

This may technically work, but the repository wants route handlers to remain thin.

The AGENTS.md communicates that expectation:

- Keep substantial business logic outside route handlers.

An agent working on the endpoint should therefore look for or create an appropriate module rather than continuously expanding the route handler.

Key Decisions

Server Components are the default

The instruction:

- Prefer Server Components unless browser APIs, client-side state, effects, or event handlers require a Client Component.

provides a decision rule rather than an absolute prohibition.

Compare it with:

- Never use Client Components.

The second instruction would make legitimate interactive UI difficult or impossible.

Route handlers stay focused

A route handler should generally coordinate HTTP concerns.

For example:

export async function POST(request: Request) {
  const input = await parseCreateUserRequest(request);
  const user = await createUser(input);

  return Response.json(user, { status: 201 });
}

The underlying business logic can then live in an appropriate application module.

Existing architecture still matters

AGENTS.md should guide the agent toward the repository's architecture, not invent a parallel architecture.

If the project already has:

src/features/

instead of:

src/lib/

the instructions should describe that actual structure.

When to Use This Pattern

Use this pattern when a Next.js App Router repository has established conventions around:

• Server and Client Components;
• route organization;
• reusable components;
• API handlers;
• server-side application logic;
• validation commands.

For larger applications, this root file can later be complemented by narrower instructions.

For example:

AGENTS.md
src/
├── app/
├── components/
└── features/
    └── billing/
        └── AGENTS.md

The root file can define application-wide conventions while the nested file describes rules specific to the billing domain.