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 APIs2. 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 types7. 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
- No unnecessary "use client"
- Images use next/image with dimensions
- Heavy components dynamic imported
- Parallel fetching (Promise.all)
Security
- Server Actions validate with Zod
- Auth in actions (not just middleware)
- IDOR prevention (user owns resource)
- No secrets in client bundles
Architecture
- Components in correct layer
- No cross-feature imports
- DRY patterns used (createSafeAction)
- URL state for shareable state
Quality
- No
anytypes - Error boundaries present
- Loading states for async
- Accessibility (semantic HTML, alt text)