nextjs-architecture-expert — Claude Code subagent for Next.js
A Claude subagent for Next.js architecture: App Router, Server Components, Pages Router migration and performance work.
npx claude-code-templates@latest --agent web-tools/nextjs-architecture-expertWhat nextjs-architecture-expert does
This subagent steps in when a Next.js project needs an architecture call: Server or Client Component, how to lay out app/, how to move off Pages Router. It carries a set of App Router practices, RSC data fetching, streaming with Suspense, ISR, and middleware for auth.
Its tools are Read, Write, Edit, Bash, Grep, Glob. So it reads and edits code in your repo instead of only talking. Migration is broken into steps: run both routers side by side, turn _app.js into layout.tsx, move pages/api/ to app/api/*/route.ts, replace getServerSideProps with Server Components, and add 'use client' where interactivity is needed.
One thing to check first: the advice assumes a Next.js project with TypeScript. On a Pages Router codebase you are not ready to restructure, the App Router guidance will not apply yet.
What it helps with
- plan an
app/layout with nested layouts and route groups - decide where
'use client'belongs and where a Server Component stays - move a project from Pages Router to App Router without freezing feature work
- set up ISR and static generation for dynamic segments
- push auth checks into
middleware.ts
Example prompts for the agent
- Help me plan the
app/structure for a dashboard with auth and analytics - This component feels slow — should it become a Server Component?
- Write a step-by-step Pages Router to App Router migration plan
How to install nextjs-architecture-expert
1claude-code-templates
npx claude-code-templates@latest --agent web-tools/nextjs-architecture-expert2Manually: put the files in place
.claude/agents/nextjs-architecture-expert.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/nextjs-architecture-expert.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/nextjs-architecture-expert.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about nextjs-architecture-expert
How do I install nextjs-architecture-expert in Claude?
Use the templates CLI: npx claude-code-templates@latest --agent web-tools/nextjs-architecture-expert. The subagent file then sits at .claude/agents/nextjs-architecture-expert.md.
What does nextjs-architecture-expert do?
It helps with Next.js architecture: App Router, Server Components, streaming, ISR, middleware, and Pages Router migration. It can read and edit files in your project.
Which tools does the subagent have?
Read, Write, Edit, Bash, Grep, Glob — reading and editing code, searching the repo, running commands.
