Next.js Senior Developer
Transform into Senior Next.js 15+/16 Engineer for production-ready App Router applications.
When to Use
- Scaffolding new Next.js App Router projects
- RSC vs Client Component decisions
- Server Actions and data fetching patterns
- Performance optimization (CWV, bundle, caching)
- Middleware and authentication setup
- Next.js 15/16 migration or audit
Version Notes
| Version |
Key Changes |
| Next.js 16 |
middleware.ts → proxy.ts, Node.js runtime only, Cache Components |
| Next.js 15 |
fetch uncached by default, React 19, Turbopack stable |
Triggers
| Command |
Purpose |
/next-init |
Scaffold new App Router project |
/next-route |
Generate route folder (page, layout, loading, error) |
/next-audit |
Audit codebase for patterns, security, performance |
/next-opt |
Optimize bundle, images, fonts, caching |
Reference Files (23 Total)
Load based on task context:
Core References
| Category |
Reference |
When |
| Routing |
references/app_router.md |
Route groups, parallel, intercepting |
| Components |
references/components.md |
RSC vs Client decision, patterns |
| Data |
references/data_fetching.md |
fetch, cache, revalidation, streaming |
| Security |
references/security.md |
Server Actions, auth, OWASP |
| Performance |
references/performance.md |
CWV, images, fonts, bundle, memory |
| Middleware |
references/middleware.md |
Auth, redirects, Edge vs Node |
Architecture & Quality
| Category |
Reference |
When |
| Architecture |
references/architecture.md |
File structure, feature-sliced design |
| Shared Components |
references/shared_components.md |
DRY patterns, composition, reusability |
| Code Quality |
references/code_quality.md |
Error handling, testing, accessibility |
Features & Integrations
| Category |
Reference |
When |
| SEO & Metadata |
references/seo_metadata.md |
generateMetadata, sitemap, OpenGraph |
| Database |
references/database.md |
Prisma, Drizzle, queries, migrations |
| Authentication |
references/authentication.md |
Auth.js, sessions, RBAC |
| Forms |
references/forms.md |
React Hook Form, Zod, file uploads |
| i18n |
references/i18n.md |
next-intl, routing, RTL support |
| Real-Time |
references/realtime.md |
SSE, WebSockets, polling, Pusher |
| API Design |
references/api_design.md |
REST, tRPC, webhooks, versioning |
DevOps & Migration
| Category |
Reference |
When |
| Deployment |
references/deployment.md |
Vercel, Docker, CI/CD, env management |
| Monorepo |
references/monorepo.md |
Turborepo, shared packages, workspaces |
| Migration |
references/migration.md |
Pages→App Router, version upgrades |
| Debugging |
references/debugging.md |
DevTools, profiling, error tracking |
| Scripts & 3rd-Party |
references/scripts.md |
next/script, loading strategies, Google Analytics |
| Self-Hosting |
references/self_hosting.md |
Docker standalone, cache handlers, multi-instance ISR |
| Debug Tricks |
references/debug_tricks.md |
MCP debugging, --debug-build-paths |
Core Tenets
1. Server-First
Default to Server Components. Use Client only when required.
RSC when: data fetching, secrets, heavy deps, no interactivity
Client when: useState, useEffect, onClick, browser APIs
2. Component Archetypes
| Pattern |
Runtime |
Must Have |
page.tsx |
Server |
async, data fetching |
*.action.ts |
Server |
"use server", Zod, 7-step security |
*.interactive.tsx |
Client |
"use client", event handlers |
*.ui.tsx |
Either |
Pure presentation, stateless |
3. 7-Step Server Action Security
"use server"
// 1. Rate limit (IP/user)
// 2. Auth verification
// 3. Zod validation (sanitize errors!)
// 4. Authorization check (IDOR prevention)
// 5. Mutation
// 6. Granular revalidateTag() (NOT revalidatePath)
// 7. Audit log (async)
4. Data Fetching Strategy
Static → generateStaticParams + fetch
ISR → fetch(url, { next: { revalidate: 60 }})
Dynamic → fetch(url, { cache: 'no-store' })
Real-time → Client fetch (SWR)
Next.js 15 Change: fetch is UNCACHED by default (opposite of 14).
5. Caching
| Type |
Scope |
Invalidation |
| Request Memoization |
Request |
Automatic |
| Data Cache |
Server |
revalidateTag() |
| Full Route Cache |
Server |
Rebuild |
| Router Cache |
Client |
router.refresh() |
Prefer revalidateTag() over revalidatePath() to avoid cache storms.
6. Feature-Sliced Architecture
For large apps (50+ routes), use domain-driven structure:
src/
├── app/ # Routing only
├── components/ # Shared UI (ui/, shared/)
├── features/ # Business logic per domain
│ └── [feature]/
│ ├── components/
│ ├── actions/
│ ├── queries/
│ └── hooks/
├── lib/ # Global utilities
└── types/ # Global types
7. Component Sharing Rules
| Used 3+ places? |
Contains business logic? |
Action |
| Yes |
No |
Move to components/ui/ or shared/ |
| Yes |
Yes |
Keep in features/ |
| No |
Any |
Keep local (_components/) |
8. State Management Hierarchy
| State Type |
Tool |
Example |
| URL State |
searchParams |
Filters, pagination |
| Server State |
Server Components |
User data, posts |
| Form State |
useActionState (React 19) |
Form submissions |
| UI State |
useState |
Modals, dropdowns |
| Shared Client |
Context/Zustand |
Theme, cart |
Rule: Prefer URL state for shareable/bookmarkable state.
9. DRY with createSafeAction
// lib/safe-action.ts - Reuse for all Server Actions
export const createPost = createSafeAction(schema, handler, {
revalidateTags: ["posts"]
})
Eliminates duplicate auth/validation/error handling.
Anti-Patterns
| Don't |
Do |
| "use client" at tree root |
Push boundary down to leaves |
| API routes for server data |
Direct DB in Server Components |
| useEffect for fetching |
Server Component async fetch |
| revalidatePath('/') |
Granular revalidateTag() |
| Trust middleware alone |
Validate at data layer too |
| Prop drill 5+ levels |
Context or composition |
any types |
Proper types or unknown |
| Barrel exports in features |
Direct imports |
| localStorage for auth |
httpOnly cookies |
| Global caches (memory leak) |
LRU cache or React cache() |
Middleware: Deny by Default
// middleware.ts - Public routes MUST be allowlisted
const publicRoutes = ['/login', '/register', '/api/health']
if (!publicRoutes.some(r => pathname.startsWith(r))) {
// Require auth
}
CRITICAL: Upgrade to Next.js 15.2.3+ (CVE-2025-29927 fix).
Scripts
| Script |
Purpose |
scripts/scaffold_route.py |
Generate route folder w/ all files |
Templates
| File |
Purpose |
templates/page.tsx |
Standard async page |
templates/layout.tsx |
Layout w/ metadata |
templates/action.ts |
7-step secure Server Action |
templates/loading.tsx |
Loading UI skeleton |
templates/error.tsx |
Error boundary |
Assets
| File |
Purpose |
assets/next.config.ts |
Production config w/ security headers |
assets/middleware.ts |
Deny-by-default auth (Next.js 15) |
assets/proxy.ts |
Deny-by-default auth (Next.js 16+) |
Quick Reference: Senior Code Review
Before merging any PR, verify:
Performance
Security
Architecture
Quality
1---2name: nextjs-senior-dev3description: Senior Next.js 15+/16 Engineer skill for App Router. Use when scaffolding production apps, enforcing RSC patterns, auditing codebases, or optimizing performance.4---56# Next.js Senior Developer78Transform into Senior Next.js 15+/16 Engineer for production-ready App Router applications.910## When to Use1112- Scaffolding new Next.js App Router projects13- RSC vs Client Component decisions14- Server Actions and data fetching patterns15- Performance optimization (CWV, bundle, caching)16- Middleware and authentication setup17- Next.js 15/16 migration or audit1819## Version Notes2021| Version | Key Changes |22|---------|-------------|23| Next.js 16 | `middleware.ts` → `proxy.ts`, Node.js runtime only, Cache Components |24| Next.js 15 | fetch uncached by default, React 19, Turbopack stable |2526## Triggers2728| Command | Purpose |29|---------|---------|30| `/next-init` | Scaffold new App Router project |31| `/next-route` | Generate route folder (page, layout, loading, error) |32| `/next-audit` | Audit codebase for patterns, security, performance |33| `/next-opt` | Optimize bundle, images, fonts, caching |3435## Reference Files (23 Total)3637Load based on task context:3839### Core References4041| Category | Reference | When |42|----------|-----------|------|43| Routing | `references/app_router.md` | Route groups, parallel, intercepting |44| Components | `references/components.md` | RSC vs Client decision, patterns |45| Data | `references/data_fetching.md` | fetch, cache, revalidation, streaming |46| Security | `references/security.md` | Server Actions, auth, OWASP |47| Performance | `references/performance.md` | CWV, images, fonts, bundle, memory |48| Middleware | `references/middleware.md` | Auth, redirects, Edge vs Node |4950### Architecture & Quality5152| Category | Reference | When |53|----------|-----------|------|54| Architecture | `references/architecture.md` | File structure, feature-sliced design |55| Shared Components | `references/shared_components.md` | DRY patterns, composition, reusability |56| Code Quality | `references/code_quality.md` | Error handling, testing, accessibility |5758### Features & Integrations5960| Category | Reference | When |61|----------|-----------|------|62| SEO & Metadata | `references/seo_metadata.md` | generateMetadata, sitemap, OpenGraph |63| Database | `references/database.md` | Prisma, Drizzle, queries, migrations |64| Authentication | `references/authentication.md` | Auth.js, sessions, RBAC |65| Forms | `references/forms.md` | React Hook Form, Zod, file uploads |66| i18n | `references/i18n.md` | next-intl, routing, RTL support |67| Real-Time | `references/realtime.md` | SSE, WebSockets, polling, Pusher |68| API Design | `references/api_design.md` | REST, tRPC, webhooks, versioning |6970### DevOps & Migration7172| Category | Reference | When |73|----------|-----------|------|74| Deployment | `references/deployment.md` | Vercel, Docker, CI/CD, env management |75| Monorepo | `references/monorepo.md` | Turborepo, shared packages, workspaces |76| Migration | `references/migration.md` | Pages→App Router, version upgrades |77| Debugging | `references/debugging.md` | DevTools, profiling, error tracking |78| Scripts & 3rd-Party | `references/scripts.md` | next/script, loading strategies, Google Analytics |79| Self-Hosting | `references/self_hosting.md` | Docker standalone, cache handlers, multi-instance ISR |80| Debug Tricks | `references/debug_tricks.md` | MCP debugging, --debug-build-paths |8182## Core Tenets8384### 1. Server-First8586Default to Server Components. Use Client only when required.8788```89RSC when: data fetching, secrets, heavy deps, no interactivity90Client when: useState, useEffect, onClick, browser APIs91```9293### 2. Component Archetypes9495| Pattern | Runtime | Must Have |96|---------|---------|-----------|97| `page.tsx` | Server | async, data fetching |98| `*.action.ts` | Server | "use server", Zod, 7-step security |99| `*.interactive.tsx` | Client | "use client", event handlers |100| `*.ui.tsx` | Either | Pure presentation, stateless |101102### 3. 7-Step Server Action Security103104```typescript105"use server"106// 1. Rate limit (IP/user)107// 2. Auth verification108// 3. Zod validation (sanitize errors!)109// 4. Authorization check (IDOR prevention)110// 5. Mutation111// 6. Granular revalidateTag() (NOT revalidatePath)112// 7. Audit log (async)113```114115### 4. Data Fetching Strategy116117```118Static → generateStaticParams + fetch119ISR → fetch(url, { next: { revalidate: 60 }})120Dynamic → fetch(url, { cache: 'no-store' })121Real-time → Client fetch (SWR)122```123124**Next.js 15 Change**: fetch is UNCACHED by default (opposite of 14).125126### 5. Caching127128| Type | Scope | Invalidation |129|------|-------|--------------|130| Request Memoization | Request | Automatic |131| Data Cache | Server | revalidateTag() |132| Full Route Cache | Server | Rebuild |133| Router Cache | Client | router.refresh() |134135Prefer `revalidateTag()` over `revalidatePath()` to avoid cache storms.136137### 6. Feature-Sliced Architecture138139For large apps (50+ routes), use domain-driven structure:140141```142src/143├── app/ # Routing only144├── components/ # Shared UI (ui/, shared/)145├── features/ # Business logic per domain146│ └── [feature]/147│ ├── components/148│ ├── actions/149│ ├── queries/150│ └── hooks/151├── lib/ # Global utilities152└── types/ # Global types153```154155### 7. Component Sharing Rules156157| Used 3+ places? | Contains business logic? | Action |158|-----------------|-------------------------|--------|159| Yes | No | Move to `components/ui/` or `shared/` |160| Yes | Yes | Keep in `features/` |161| No | Any | Keep local (`_components/`) |162163### 8. State Management Hierarchy164165| State Type | Tool | Example |166|------------|------|---------|167| URL State | searchParams | Filters, pagination |168| Server State | Server Components | User data, posts |169| Form State | useActionState (React 19) | Form submissions |170| UI State | useState | Modals, dropdowns |171| Shared Client | Context/Zustand | Theme, cart |172173**Rule**: Prefer URL state for shareable/bookmarkable state.174175### 9. DRY with createSafeAction176177```typescript178// lib/safe-action.ts - Reuse for all Server Actions179export const createPost = createSafeAction(schema, handler, {180 revalidateTags: ["posts"]181})182```183184Eliminates duplicate auth/validation/error handling.185186## Anti-Patterns187188| Don't | Do |189|-------|-----|190| "use client" at tree root | Push boundary down to leaves |191| API routes for server data | Direct DB in Server Components |192| useEffect for fetching | Server Component async fetch |193| revalidatePath('/') | Granular revalidateTag() |194| Trust middleware alone | Validate at data layer too |195| Prop drill 5+ levels | Context or composition |196| `any` types | Proper types or `unknown` |197| Barrel exports in features | Direct imports |198| localStorage for auth | httpOnly cookies |199| Global caches (memory leak) | LRU cache or React cache() |200201## Middleware: Deny by Default202203```typescript204// middleware.ts - Public routes MUST be allowlisted205const publicRoutes = ['/login', '/register', '/api/health']206if (!publicRoutes.some(r => pathname.startsWith(r))) {207 // Require auth208}209```210211**CRITICAL**: Upgrade to Next.js 15.2.3+ (CVE-2025-29927 fix).212213## Scripts214215| Script | Purpose |216|--------|---------|217| `scripts/scaffold_route.py` | Generate route folder w/ all files |218219## Templates220221| File | Purpose |222|------|---------|223| `templates/page.tsx` | Standard async page |224| `templates/layout.tsx` | Layout w/ metadata |225| `templates/action.ts` | 7-step secure Server Action |226| `templates/loading.tsx` | Loading UI skeleton |227| `templates/error.tsx` | Error boundary |228229## Assets230231| File | Purpose |232|------|---------|233| `assets/next.config.ts` | Production config w/ security headers |234| `assets/middleware.ts` | Deny-by-default auth (Next.js 15) |235| `assets/proxy.ts` | Deny-by-default auth (Next.js 16+) |236237## Quick Reference: Senior Code Review238239Before merging any PR, verify:240241**Performance**242- [ ] No unnecessary "use client"243- [ ] Images use next/image with dimensions244- [ ] Heavy components dynamic imported245- [ ] Parallel fetching (Promise.all)246247**Security**248- [ ] Server Actions validate with Zod249- [ ] Auth in actions (not just middleware)250- [ ] IDOR prevention (user owns resource)251- [ ] No secrets in client bundles252253**Architecture**254- [ ] Components in correct layer255- [ ] No cross-feature imports256- [ ] DRY patterns used (createSafeAction)257- [ ] URL state for shareable state258259**Quality**260- [ ] No `any` types261- [ ] Error boundaries present262- [ ] Loading states for async263- [ ] Accessibility (semantic HTML, alt text)