A CLAUDE.md template for Next.js projects

What belongs in your CLAUDE.md?

Put a short CLAUDE.md in your project root. Treat it as a map of this repository, not a generic prompt telling an assistant to be an expert. The useful details are easy to check: your package manager, real scripts, where server-only code lives, and what verification must happen before a change is finished.

Next.js makes this especially important. A component that needs state or event handlers belongs behind a client boundary; your database credentials do not. A vague “use best practices” instruction does not explain that split.

This template is a starting point you can use without buying anything. It is instruction text, not enforcement. Keep permission prompts, review and CI.

Copy this into your project root

Replace every angle-bracket placeholder with a value from your repository. Delete any command or rule that does not apply. Do not paste real secrets into this file.

# Next.js project instructions

## Project
- Next.js App Router, React and TypeScript.
- Package manager: <npm, pnpm, yarn or bun — choose the installed one>.
- Node version: <copy from package.json or .nvmrc>.

## Commands — verify these against package.json
- Develop: <package-manager> run dev
- Typecheck: <your existing typecheck command>
- Lint: <your existing lint command>
- Test: <your existing test command>
- Build: <package-manager> run build
- Do not invent missing scripts or report unrun checks as passing.

## Server/client boundary
- Keep pages and layouts as Server Components unless they need browser behavior.
- Put "use client" at the top of the smallest interactive component.
- Keep database access, secrets and next/headers on the server.
- Pass serializable props into Client Components.
- Do not export metadata from a Client Component or make it async.

## Data and caching
- Use the repository's existing data-access and authentication patterns.
- State whether each new fetch should be cached, revalidated or dynamic.
- Check the installed Next.js version before assuming caching defaults.
- After a mutation, invalidate the affected data or path using that version's API.

## Secrets and generated files
- Do not read or edit .env or .env.local; use placeholder values in .env.example.
- NEXT_PUBLIC_ variables are public. Never prefix a secret with NEXT_PUBLIC_.
- Change source files, not .next/, node_modules/ or next-env.d.ts.
- Change package.json and use the package manager to update lockfiles.

## Scope and verification
- Make the smallest complete change. Keep unrelated files untouched.
- Do not add dependencies without explaining why they are needed.
- Run the affected checks and a production build for routing/boundary changes.
- Report changed files, checks actually run and remaining uncertainty.
- Never force-push, reset --hard or delete untracked work.

Adapt it in five minutes

1. Read package.json first. Use the existing package manager and script names. If there is no lint or test script, say so rather than inventing a successful check.
2. Locate the application. Add whether routes live in app/ or src/app/, and name your existing data and authentication modules. Avoid documenting a folder that does not exist.
3. Check your Next.js version. Caching behavior and APIs vary across versions. Write the intended behavior for each changed fetch; do not blindly copy an older caching recipe.
4. Remove irrelevant rules. A small set of specific instructions is easier to review than a long, contradictory file. Keep security-critical boundaries, not a wish list of coding styles.
5. Try a bounded task. On a working branch, ask Claude to explain where a new interactive filter would live before editing. Check whether it keeps data access on the server and proposes a small client component.

Three mistakes this helps you catch

Moving an entire page to the client

If only a filter needs state, isolate the filter. Keep the surrounding data-loading page on the server and pass the data it needs as serializable props. Do not move secrets into a client bundle to make an import error disappear.

Assuming every Next.js version caches the same way

Ask for an explicit caching choice and check it against the installed version. After a mutation, verify that the affected view actually updates; a successful build alone does not establish freshness.

Treating written rules as a security boundary

A CLAUDE.md request not to edit .env.local is guidance. It can be missed. Permission controls and narrow hooks provide additional checks, but they do not replace review or make arbitrary shell commands safe.

When should you add hooks?

Already configured a hook but it does not run? Use the six-step hook troubleshooting checklist to separate configuration from script logic.

Start with the free template. If the same mistakes keep recurring, add checks at the point where a tool acts. The free protect-files hook sample shows how an edit to a secret file or generated output can be blocked. Download the free sample ZIP, inspect its source and run node verify.mjs to check seven fictional paths without touching real secrets. Its setup guide shows how to preserve your existing settings.

Frequently asked questions

Is CLAUDE.md the same as hooks?

No. CLAUDE.md gives project instructions. Hooks run configured commands around tool actions. Use both only where they address a real failure mode, and inspect commands before enabling them.

Will this work with the Pages Router?

The server/client component guidance here targets the App Router. Do not apply it unchanged to a Pages Router project.

Should I commit CLAUDE.md?

Commit shared, non-secret project instructions if that fits your team's workflow. Keep private machine details, credentials and personal instructions out of the shared file.