nextjs

skill:nextjs - Next.js 16 Expert

Version: 1.0.0

Purpose

Build production-grade Next.js 16 applications using App Router, React Server Components, Server Actions, Cache Components ("use cache" ), and async route params. This skill covers the full Next.js 16 development lifecycle including routing, data fetching, caching, authentication (proxy.ts), middleware, and deployment. Use when building new Next.js apps, migrating from Pages Router, upgrading to Next.js 16, or implementing complex data fetching patterns.

File Structure

skills/nextjs/ ├── SKILL.md (this file) └── examples.md

Interface References

Context: Loaded via ContextProvider Interface
Memory: Accessed via MemoryStore Interface
Shared Patterns: Shared Loading Patterns
Schemas: Validated against context_metadata.schema.json and memory_entry.schema.json

Next.js 16 Focus Areas

App Router: File-based routing with layouts, loading states, error boundaries, and parallel routes
Server Components: Default rendering model — no client JS unless "use client" is declared
Server Actions: Mutations via "use server" functions — form handling, data writes, revalidation
Cache Components: "use cache" directive for granular caching at component and function level
Async Route Params: params and searchParams are now Promises — must be awaited
proxy.ts: Auth proxy pattern for secure API route handling (replaces middleware-based auth)
React 19.2: use() hook, <Suspense> boundaries, useActionState , useOptimistic
Metadata API: Static and dynamic metadata generation for SEO
Streaming: Progressive rendering with Suspense boundaries for improved TTFB

Common Errors Prevented

Using "use client" unnecessarily — defaulting to Server Components reduces bundle size
Accessing params synchronously (Next.js 16 requires await params )
Importing client-only code in Server Components (window, localStorage, hooks)
Using fetch() in Server Actions instead of direct database access
Missing revalidatePath() or revalidateTag() after mutations
Incorrect "use cache" placement (must be top of file or top of function)
Passing non-serializable props from Server to Client Components
Missing loading.tsx for routes with async data fetching
Using router.push() for mutations instead of Server Actions
Incorrect generateStaticParams() return type
Missing error.tsx boundary causing full-page crashes
Cookie/header access in cached components (breaks caching)
Circular dependencies between Server and Client Components
Missing Suspense boundary around use() hook calls
redirect() called inside try/catch blocks (throws NEXT_REDIRECT error)
Using useSearchParams() without <Suspense> boundary (blocks static rendering)
Middleware matching too broadly (applying to static assets)
Missing proxy.ts for third-party auth providers in production
Stale closures in Server Actions capturing outdated state
Setting dynamic = "force-static" on routes that read cookies/headers
Using Date.now() in Server Components causing hydration mismatch
Forgetting export const runtime = "edge" for edge-deployed routes
Nesting <form action={serverAction}> inside client-side form libraries
Missing key prop when rendering dynamic route segments
Using next/image without configured remotePatterns in next.config

MANDATORY WORKFLOW (MUST FOLLOW EXACTLY)

Step 1: Initial Analysis

YOU MUST:

Detect the Next.js version and router type (App Router vs. Pages Router)
Identify the scope:
New Next.js 16 application setup
Feature implementation (routing, data fetching, forms, auth)
Migration from Pages Router or older Next.js
Performance optimization or caching strategy
Check next.config.js /next.config.ts for configuration
Identify deployment target (Vercel, self-hosted, Docker, Cloudflare)
Ask clarifying questions if ambiguous

Step 2: Load Memory

Follow Standard Memory Loading with skill="nextjs" and domain="engineering" .

YOU MUST:

Use memoryStore.getSkillMemory("nextjs", "{project-name}") to load project patterns
Use memoryStore.getByProject("{project-name}") for cross-skill context
Review previously documented route structure, caching strategy, and auth patterns

Step 3: Load Context

Follow Standard Context Loading for the engineering domain. Stay within the file budget declared in frontmatter.

Step 4: Implement Next.js Patterns

YOU MUST follow these rules:

Server Components (Default):

All components are Server Components unless marked "use client"
Can directly access databases, file systems, and environment variables
Cannot use hooks (useState , useEffect ), event handlers, or browser APIs
Props passed to Client Components must be serializable (no functions, classes, or Dates)

Client Components:

Only add "use client" when you need interactivity, hooks, or browser APIs
Push "use client" boundary as deep as possible in the component tree
Prefer composition: pass Server Component as children to Client Component

Server Actions:

"use server" // Must be async, can only be called from client-side or form actions export async function createItem(formData: FormData) { // Direct database/API access // Always revalidate after mutation revalidatePath("/items") }

Cache Components (Next.js 16):

"use cache" // Caches the component/function output // Cannot access cookies, headers, or other dynamic APIs export default async function ProductList() { const products = await db.query("SELECT * FROM products") return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul> }

Async Route Params (Next.js 16):

// params is now a Promise - must await export default async function Page({ params, }: { params: Promise<{ slug: string }> }) { const { slug } = await params // ... }

DO NOT use "use client" unless strictly necessary

Step 5: Generate Output

Save to /claudedocs/nextjs_{project}_{YYYY-MM-DD}.md
Follow naming conventions in ../OUTPUT_CONVENTIONS.md
Include file paths, code changes, and configuration updates

Step 6: Update Memory

Follow Standard Memory Update for skill="nextjs" .

Store route structure, caching strategy, auth patterns, deployment config, and component boundaries.

Compliance Checklist

Before completing, verify:

Step 1: Next.js version, router type, and scope identified
Step 2: Standard Memory Loading pattern followed
Step 3: Standard Context Loading pattern followed
Step 4: Next.js patterns correctly applied (Server/Client boundaries, caching, async params)
Step 5: Output saved with standard naming convention
Step 6: Standard Memory Update pattern followed

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

office

accessibility

jquery-4