# nextjs-architecture-expert

A Claude subagent for Next.js architecture: App Router, Server Components, Pages Router migration and performance work.

- subagent · `type=agent` · Claude Code · 4935 installs
- Author: davila7
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/agents/web-tools/nextjs-architecture-expert.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/agents/nextjs-architecture-expert

## What it 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.

## Install

### Claude Code (native platform)

1. **claude-code-templates**
```bash
npx claude-code-templates@latest --agent web-tools/nextjs-architecture-expert
```

2. **Manually: put the files in place**
- File: `.claude/agents/nextjs-architecture-expert.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/nextjs-architecture-expert.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/nextjs-architecture-expert.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/agents/web-tools/nextjs-architecture-expert.md

## When to use it
- 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
- 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

## Similar
- [nextjs-app-router-patterns](https://affpapa.org/en/nevibecode/skills/nextjs-app-router-patterns.md) — skill · 32529 installs
- [frontend-developer](https://affpapa.org/en/nevibecode/agents/voltagent-community-frontend-developer.md) — subagent · 40905 installs
- [ui-ux-designer](https://affpapa.org/en/nevibecode/agents/ui-ux-designer.md) — subagent · 27069 installs
- [fullstack-developer](https://affpapa.org/en/nevibecode/agents/fullstack-developer.md) — subagent · 18117 installs
- [javascript-pro](https://affpapa.org/en/nevibecode/agents/javascript-pro.md) — subagent · 4974 installs
- [ui-designer](https://affpapa.org/en/nevibecode/agents/voltagent-community-ui-designer.md) — subagent · 1979 installs
- [ui-designer](https://affpapa.org/en/nevibecode/agents/ui-designer.md) — subagent · 1979 installs

From the same set: [davila7/claude-code-templates](https://affpapa.org/en/nevibecode/by/davila7/claude-code-templates.md) — 224 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md