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 |
useFormState |
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---5
6# Next.js Senior Developer
7
8Transform into Senior Next.js 15+/16 Engineer for production-ready App Router applications.
9
10## When to Use
11
12- Scaffolding new Next.js App Router projects
13- RSC vs Client Component decisions
14- Server Actions and data fetching patterns
15- Performance optimization (CWV, bundle, caching)
16- Middleware and authentication setup
17- Next.js 15/16 migration or audit
18
19## Version Notes
20
21| 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 |
25
26## Triggers
27
28| 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 |
34
35## Reference Files (23 Total)
36
37Load based on task context:
38
39### Core References
40
41| 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 |
49
50### Architecture & Quality
51
52| 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 |
57
58### Features & Integrations
59
60| 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 |
69
70### DevOps & Migration
71
72| 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 |
81
82## Core Tenets
83
84### 1. Server-First
85
86Default to Server Components. Use Client only when required.
87
88```
89RSC when: data fetching, secrets, heavy deps, no interactivity
90Client when: useState, useEffect, onClick, browser APIs
91```
92
93### 2. Component Archetypes
94
95| 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 |
101
102### 3. 7-Step Server Action Security
103
104```typescript
105"use server"
106// 1. Rate limit (IP/user)
107// 2. Auth verification
108// 3. Zod validation (sanitize errors!)
109// 4. Authorization check (IDOR prevention)
110// 5. Mutation
111// 6. Granular revalidateTag() (NOT revalidatePath)
112// 7. Audit log (async)
113```
114
115### 4. Data Fetching Strategy
116
117```
118Static → generateStaticParams + fetch
119ISR → fetch(url, { next: { revalidate: 60 }})
120Dynamic → fetch(url, { cache: 'no-store' })
121Real-time → Client fetch (SWR)
122```
123
124**Next.js 15 Change**: fetch is UNCACHED by default (opposite of 14).
125
126### 5. Caching
127
128| 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() |
134
135Prefer `revalidateTag()` over `revalidatePath()` to avoid cache storms.
136
137### 6. Feature-Sliced Architecture
138
139For large apps (50+ routes), use domain-driven structure:
140
141```
142src/
143├── app/ # Routing only
144├── components/ # Shared UI (ui/, shared/)
145├── features/ # Business logic per domain
146│ └── [feature]/
147│ ├── components/
148│ ├── actions/
149│ ├── queries/
150│ └── hooks/
151├── lib/ # Global utilities
152└── types/ # Global types
153```
154
155### 7. Component Sharing Rules
156
157| 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/`) |
162
163### 8. State Management Hierarchy
164
165| State Type | Tool | Example |
166|------------|------|---------|
167| URL State | searchParams | Filters, pagination |
168| Server State | Server Components | User data, posts |
169| Form State | useFormState | Form submissions |
170| UI State | useState | Modals, dropdowns |
171| Shared Client | Context/Zustand | Theme, cart |
172
173**Rule**: Prefer URL state for shareable/bookmarkable state.
174
175### 9. DRY with createSafeAction
176
177```typescript
178// lib/safe-action.ts - Reuse for all Server Actions
179export const createPost = createSafeAction(schema, handler, {
180 revalidateTags: ["posts"]
181})
182```
183
184Eliminates duplicate auth/validation/error handling.
185
186## Anti-Patterns
187
188| 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() |
200
201## Middleware: Deny by Default
202
203```typescript
204// middleware.ts - Public routes MUST be allowlisted
205const publicRoutes = ['/login', '/register', '/api/health']
206if (!publicRoutes.some(r => pathname.startsWith(r))) {
207 // Require auth
208}
209```
210
211**CRITICAL**: Upgrade to Next.js 15.2.3+ (CVE-2025-29927 fix).
212
213## Scripts
214
215| Script | Purpose |
216|--------|---------|
217| `scripts/scaffold_route.py` | Generate route folder w/ all files |
218
219## Templates
220
221| 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 |
228
229## Assets
230
231| 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+) |
236
237## Quick Reference: Senior Code Review
238
239Before merging any PR, verify:
240
241**Performance**
242- [ ] No unnecessary "use client"
243- [ ] Images use next/image with dimensions
244- [ ] Heavy components dynamic imported
245- [ ] Parallel fetching (Promise.all)
246
247**Security**
248- [ ] Server Actions validate with Zod
249- [ ] Auth in actions (not just middleware)
250- [ ] IDOR prevention (user owns resource)
251- [ ] No secrets in client bundles
252
253**Architecture**
254- [ ] Components in correct layer
255- [ ] No cross-feature imports
256- [ ] DRY patterns used (createSafeAction)
257- [ ] URL state for shareable state
258
259**Quality**
260- [ ] No `any` types
261- [ ] Error boundaries present
262- [ ] Loading states for async
263- [ ] Accessibility (semantic HTML, alt text)