How to Do Next.js App Router Setup on Claude Code

The fastest way to scaffold a Next.js App Router project with Claude Code is to open a terminal, run claude in your project directory, and give it a single, explicit prompt describing your full folder structure. Claude Code will generate the app/ directory, layouts, pages, and route groups in one pass, without you leaving your editor. Use Usagebar to monitor usage in your macOS menu bar so a 5-hour lockout does not kill the session mid-scaffold.

• Target audience: developers bootstrapping a new Next.js 13+ project or migrating from the Pages Router
• Key trade-off: letting Claude Code generate boilerplate is fast, but you still need to review layout.tsx and loading.tsx files for project-specific concerns
• Claude Code works inside your existing repo with full file-system access, so it writes real files, not just code snippets

What is the Next.js App Router and why does it matter for Claude Code?

The Next.js App Router, introduced in Next.js 13 and stabilised in Next.js 14, replaces the pages/ directory with an app/ directory. It adds React Server Components, nested layouts, streaming, and a new file-based routing convention (page.tsx, layout.tsx, loading.tsx, error.tsx).

Because the App Router has a very consistent file-naming convention, Claude Code is particularly good at generating it. The model understands the spec well enough to produce correct route groups, parallel routes, and intercepting routes without hand-holding. That makes it an ideal task to delegate entirely, as long as your prompt is precise.

How to scaffold Next.js App Router with Claude Code step by step

1. Start a new project or open an existing repo

Run npx create-next-app@latest my-app to get the base scaffold, or cd into an existing repo. Then start Claude Code:

claude

Claude Code reads your working directory automatically, so it knows what already exists before it writes anything.

2. Give Claude Code a single, structured prompt

A vague prompt produces vague results. Be explicit about your route structure. For example:

Set up a Next.js App Router structure with the following routes:
- / (home page, static)
- /dashboard (authenticated, shared layout with sidebar)
- /dashboard/settings (nested under dashboard)
- /blog/[slug] (dynamic route, SSR)
- /api/health (API route)

Use TypeScript. Add a root layout with Inter font and a <main> wrapper.
Add loading.tsx and error.tsx for the dashboard segment.
Do not install extra dependencies.

The more concrete your requirements, the less iteration you need and the fewer tokens you spend.

3. Review generated files before running the dev server

Claude Code will create the files and show you a diff. Check:

• app/layout.tsx for your root <html> and <body> tags
• app/dashboard/layout.tsx for any shared authenticated wrapper
• That page.tsx files export a default React component (not just a named export)
• That dynamic segments use the correct params prop type: { params: { slug: string } }

4. Iterate with follow-up prompts

Once the base structure is in place, continue in the same Claude Code session:

Add a (marketing) route group for /, /about, and /pricing
that shares a navbar layout but is separate from the dashboard layout.

Claude Code keeps full context of what it already wrote, so incremental changes are clean.

5. Use slash commands to keep the session focused

Claude Code supports slash commands that help you manage long sessions. Useful ones for scaffolding work:

• /clear to reset the conversation context when switching to a different part of the codebase
• /compact to summarise the session history and free up context window space
• /usage to check your current API usage directly inside the terminal

Common App Router patterns Claude Code handles well

Pattern	What to ask Claude Code	Files generated
Route groups	"Create a (auth) group for /login and /signup with a centred card layout"	app/(auth)/layout.tsx, app/(auth)/login/page.tsx
Parallel routes	"Add @modal and @page slots to the dashboard layout"	app/dashboard/@modal/, app/dashboard/@page/
Intercepting routes	"Intercept /photos/[id] to show a modal when navigating from the gallery"	app/(..)photos/[id]/page.tsx
Server Actions	"Add a form submission server action for the contact page"	app/contact/actions.ts, updated page.tsx
Metadata API	"Add static and dynamic metadata to the blog slug page"	Updated app/blog/[slug]/page.tsx with generateMetadata

For server actions specifically, see our guide on how to do Next.js server actions on Claude Code for prompt patterns that avoid common pitfalls.

Why you should monitor usage while doing this

Scaffolding an App Router project is a multi-step task. You are likely to spend 20-40 minutes in a single Claude Code session across several prompts. Anthropic's usage limits reset on a 5-hour rolling window, and if you hit your ceiling mid-session while wrapping up a PR, you lose access until the window resets.

That context switch is expensive. You lose flow, you forget what you were in the middle of, and the scaffolding task stalls.

Usagebar sits in your macOS menu bar and shows you live Claude Code usage. It fires notifications at 50%, 75%, and 90% of your limit so you know to wrap up the current task before you hit the wall, not after. It stores your credentials in the macOS Keychain (never plain text), and you can check the exact time your usage window resets. There is a pay-what-you-want model and a free option for students.

You can also run /usage inside Claude Code at any time, or visit claude.ai/settings/usage for a full breakdown.

For a deeper look at how usage tracking works, see how to check your Claude Code usage limits and whether Claude Code usage affects your Pro limits.

Key takeaways

1. Start Claude Code in your project directory, then give it a single detailed prompt listing all routes, layout relationships, and TypeScript requirements.
2. Use route groups ((groupname)) to share layouts without affecting the URL path. Explicitly ask Claude Code for them by name.
3. Review layout.tsx files first. They are the most likely place for project-specific customisation that Claude Code cannot infer.
4. Use /compact to keep the context window healthy across a long scaffolding session.
5. Monitor usage with Usagebar or /usage to avoid a 5-hour lockout mid-build.

Get Usagebar

Stop guessing when your Claude Code session will hit a wall. Get Usagebar for instant menu bar visibility into your usage, smart threshold alerts, and reset-time tracking. Download is instant, pricing is flexible, and there is a free tier for students.

Sources

• https://nextjs.org/docs/app
• https://docs.anthropic.com/en/docs/claude-code/slash-commands
• https://support.claude.com/en/articles/9797557-usage-limit-best-practices
• https://claude.ai/settings/usage