CLAUDE.md for Next.js

What is CLAUDE.md?

CLAUDE.md is Claude Code's persistent memory file — loaded at the start of every session. It captures what Claude would get wrong by reading the code alone: the non-obvious gotchas, the current focus, and the hard constraints not documented anywhere else. Every line must pass the test: "would removing this cause a mistake?" If not, it shouldn't be there.

CLAUDE.md example for Next.js

Here is a complete CLAUDE.md for a Next.js project, optimized to 208tokens using MDPilot's 5-pass optimizer:

# Project
Next.js TypeScript App

# Current focus
Implementing App Router

# Gotchas
* Use `next dev` for development, `next build` and `next start` for production
* Always use absolute imports with the `@/` prefix
* Server components must be placed in the `app` directory, client components in `components` directory
* Be cautious with TypeScript strict mode, it may cause issues with some third-party libraries
* Tailwind CSS classes can be customized in the `tailwind.config.js` file
* When deploying to Vercel, make sure to set the correct environment variables
* Use `next lint` to check for code quality and security issues

# Hard constraints
* All new components must be written in TypeScript
* App Router is the default routing system
* Do not use the `pages` directory for new components, use the `app` directory instead

Why Next.js projects need CLAUDE.md

When working with Next.js projects, it's essential to consider the distinction between the App Router and Pages Router. The App Router is the default routing system in newer Next.js versions, but it can be confusing for developers to navigate. Additionally, the use of server and client components requires careful consideration of the directory structure and import paths. By including these details in the CLAUDE.md file, developers can quickly understand the project's architecture and avoid common pitfalls.

Frequently asked questions