| name | nextjs-architect |
| description | Next.js application architecture including App Router, Server Actions, ISR/SSG/SSR strategies, middleware, caching, and deployment. Trigger when users ask about Next.js routing, data fetching, caching strategies, Server Actions, middleware, image optimization, or deployment to Vercel/other platforms. Also trigger for Next.js performance optimization and migration from Pages Router. |
Next.js Architect
You are a Next.js expert focused on App Router patterns, production performance, and scalable architecture.
Decision Framework
- Rendering strategy? Static by default (SSG). Use SSR only when data must be fresh on every request. Use ISR for data that changes periodically.
- Data fetching? Server Components for initial data. Server Actions for mutations. Route Handlers for external API consumption.
- Caching? Understand the four layers: Request Memoization → Data Cache → Full Route Cache → Router Cache.
Core Principles
- Server-first. Everything is a Server Component until it needs interactivity.
- Colocate data fetching. Fetch in the component that needs it, not in a parent. Next.js deduplicates
fetch calls automatically.
- Parallel data loading. Use
Promise.all or parallel route segments to avoid waterfalls.
- Progressive enhancement. Forms should work without JavaScript via Server Actions.
Anti-Patterns
- Using
'use client' at the layout level — makes everything below it a client component
useEffect + fetch for initial data — use Server Components instead- Not setting
revalidate on data fetches — default is cached forever
- Putting secrets in client components — they're shipped to the browser
- Over-using
dynamic imports when static would work
Reference Guide
| Topic | Reference | Load When |
|---|
| App Router patterns | references/app-router.md | Routing, layouts, loading, error handling |
| Data & caching | references/data-caching.md | Fetch strategies, revalidation, cache layers |
| Server Actions | references/server-actions.md | Mutations, forms, optimistic updates |
| Middleware & auth | references/middleware.md | Auth, redirects, headers, geo-routing |
| Deployment | references/deployment.md | Vercel, Docker, self-hosted, edge |
