Next.js 15 App Router Project Instructions
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.
The skill file
Claude Code · CLAUDE.mdCLAUDE.md3133 chars
# 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.
Install
drop into your repoSave this to your project or home directory so Claude Code can load it.
path./CLAUDE.md
Discussion
What people are saying
Forks
0 forks of this skillLoading forks…