Next.js 15 App Router Project Instructions
Claude CodeCLAUDE.mdCoding
CLAUDE.md template for Next.js 15 App Router projects: server-component defaults, data-fetching rules, file layout, and the commands an agent should run before committing.
Use when: Drop into the root of a Next.js 15+ project using the App Router so coding agents follow your server/client component boundaries and caching conventions instead of guessing.
Get this skill
Add the skill file with the CLI, by hand, or over MCP.Save this to your project or home directory so Claude Code can load it.
npx goodprompts add nextjs-app-router-claude-mdSaves to
./CLAUDE.mdnpx goodprompts add nextjs-app-router-claude-mdSaves to
./CLAUDE.mdSkill file
CLAUDE.md3,133 characters# Project Instructions — Next.js 15 (App Router)
## Stack
Next.js 15 (App Router) · React 19 · TypeScript strict · Tailwind CSS · <your-orm> · deployed on <your-platform>.
## Commands
```bash
pnpm dev # dev server → http://localhost:3000
pnpm build # production build — must pass before any PR
pnpm lint # eslint + next lint rules
pnpm typecheck # tsc --noEmit
pnpm test # unit tests
```
Run `pnpm lint && pnpm typecheck && pnpm build` before declaring any task done. A change that breaks `pnpm build` is not done.
## Server vs. client components
- **Server components are the default.** Do not add `"use client"` unless the component needs state, effects, event handlers, or browser-only APIs.
- When a component needs interactivity, isolate the interactive part into the smallest possible client component and keep the parent on the server. Never convert an entire page to a client component to fix one click handler.
- Never import server-only modules (DB clients, secrets, `server-only` packages) into a file marked `"use client"`.
- Pass serializable props across the server/client boundary only — no functions, class instances, or Dates without serialization.
## Data fetching
- Fetch data in server components or route handlers, not in `useEffect`. Client-side fetching is allowed only for live/polling data, and goes through <your-query-library>.
- Mutations go through Server Actions in `src/actions/`. Every action: validate input with zod, check auth first, return a typed `{ ok, error }` result — never throw raw errors to the client.
- After a mutation, call `revalidatePath` or `revalidateTag` explicitly. State what you revalidated in the PR description.
- Be deliberate about caching: Next 15 does not cache `fetch` by default. Add `next: { revalidate: <seconds> }` or `cache: "force-cache"` intentionally, with a comment saying why.
## File layout
```
src/app/ # routes only: page.tsx, layout.tsx, loading.tsx, error.tsx, route.ts
src/components/ # shared components (ui/ for primitives, feature dirs otherwise)
src/actions/ # server actions, one file per domain
src/lib/ # pure utilities, no React imports
src/db/ # schema + queries; the only place that touches the database
```
- Route directories contain routing files only. Page-specific components live in a `_components/` folder inside the route, which Next excludes from routing.
- Every route that fetches data gets a `loading.tsx`. Every route group gets an `error.tsx`.
## Rules
- Use `next/image` for all images and `next/link` for internal navigation — never `<img>` or `<a href="/...">`.
- Read route params via the async `params`/`searchParams` props (they are Promises in Next 15 — `await` them).
- Metadata via the `metadata` export or `generateMetadata`; never hand-write `<head>` tags.
- Environment variables are read only in `src/env.ts` with zod validation. `NEXT_PUBLIC_` prefix only for values that are genuinely safe in the browser bundle.
- Do not edit `next.config.ts` or middleware without flagging it in your summary — these affect every route.