Next.js Senior Developer Skill

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

[ ] 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 any types
[ ] Error boundaries present
[ ] Loading states for async
[ ] Accessibility (semantic HTML, alt text)

Agent Skills: Next.js Senior Developer

Install this agent skill to your local

Skill Files