/nextjs

name: nextjs
description: "Next.js 16 with App Router, Server Components, Server Actions, Cache Components. Use for React 19.2 apps, SSR, or encountering async params, proxy.ts migration, use cache errors."
license: MIT
metadata:
  version: 1.0.0
  last_verified: 2025-11-21
  nextjs_version: 16.2.0
  react_version: 19.2.0
  node_version: 20.9+
  author: Claude Skills Maintainers
  repository: https://github.com/secondsky/claude-skills
  production_tested: true
  token_savings: 65-70%
  errors_prevented: 18+
  keywords:
    - Next.js 16
    - Next.js App Router
    - Next.js Pages Router
    - Server Components
    - React Server Components
    - Server Actions
    - Cache Components
    - use cache
    - Next.js 16 breaking changes
    - async params nextjs
    - proxy.ts migration
    - React 19.2
    - Next.js metadata
    - Next.js SEO
    - generateMetadata
    - static generation
    - dynamic rendering
    - streaming SSR
    - Suspense
    - parallel routes
    - intercepting routes
    - route groups
    - Next.js middleware
    - Next.js API routes
    - Route Handlers
    - revalidatePath
    - revalidateTag
    - next/navigation
    - useSearchParams
    - turbopack
    - next.config
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

Next.js App Router - Production Patterns

**Version**: Next.js 16.2.0 **React Version**: 19.2.0 **Node.js**: 20.9+ **Last Verified**: 2025-11-21

Table of Contents

1. [When to Use This Skill](#when-to-use-this-skill) 2. [When NOT to Use This Skill](#when-not-to-use-this-skill) 3. [Next.js 16 Breaking Changes](#nextjs-16-breaking-changes) 4. [Cache Components & Caching APIs](#cache-components--caching-apis) 5. [Server Components](#server-components) 6. [Server Actions](#server-actions) 7. [Route Handlers](#route-handlers) 8. [React 19.2 Features](#react-192-features) 9. [Metadata API](#metadata-api) 10. [Image & Font Optimization](#image--font-optimization) 11. [Top 5 Critical Errors](#top-5-critical-errors) 12. [Performance Patterns](#performance-patterns) 13. [TypeScript Configuration](#typescript-configuration)

---

When to Use This Skill

Use this skill when you need:

• **Next.js 16 App Router patterns** (layouts, loading, error boundaries, routing)
• **Server Components** best practices (data fetching, composition, streaming)
• **Server Actions** patterns (forms, mutations, revalidation, error handling)
• **Cache Components** with `"use cache"` directive (NEW in Next.js 16)
• **New caching APIs**: `revalidateTag()`, `updateTag()`, `refresh()` (Updated in Next.js 16)
• **Migration from Next.js 15 to 16** (async params, proxy.ts, parallel routes)
• **Route Handlers** (API endpoints, webhooks, streaming responses)
• **Proxy patterns** (`proxy.ts` replaces `middleware.ts` in Next.js 16)
• **Async route params** (`params`, `searchParams`, `cookies()`, `headers()` now async)
• **Parallel routes with default.js** (breaking change in Next.js 16)
• **React 19.2 features** (View Transitions, `useEffectEvent()`, React Compiler)
• **Metadata API** (SEO, Open Graph, Twitter Cards, sitemaps)
• **Image optimization** (`next/image` with updated defaults in Next.js 16)
• **Performance optimization** (lazy loading, code splitting, PPR, ISR)

When NOT to Use This Skill

Do NOT use this skill for:

• **Cloudflare Workers deployment** → Use the **`cloudflare-nextjs`** skill (OpenNext adapter: `@opennextjs/cloudflare`, `getCloudflareContext`, caching tiers, Workers-specific errors). Note: `cloudflare-nextjs` covers the `proxy.ts` exception for Cloudflare (keep `middleware.ts` there).
• **Pages Router patterns** → This skill covers App Router ONLY (Pages Router is legacy)
• **Authentication libraries** → Use `clerk-auth`, `auth-js`, or other auth-specific skills
• **Database integration** → Use `cloudflare-d1`, `drizzle-orm-d1`, or database-specific skills
• **UI component libraries** → Use `tailwind-v4-shadcn` skill for Tailwind + shadcn/ui
• **State management** → Use `zustand-state-management`, `tanstack-query` skills
• **Form libraries** → Use `react-hook-form-zod` skill

---

Next.js 16 Breaking Changes

**CRITICAL**: Next.js 16 has multiple breaking changes. For detailed migration steps, see `references/next-16-migration-guide.md`.

| Breaking Change | Before | After | |-----------------|--------|-------| | **Async params** | `params.slug` | `const { slug } = await params` | | **Async headers** | `cookies()` sync | `await cookies()` | | **Middleware** | `middleware.ts` | `proxy.ts` (renamed) | | **Parallel routes** | `default.js` optional | `default.js` **required** | | **Caching** | Auto-cached fetch | Opt-in with `"use cache"` | | **revalidateTag()** | 1 argument | 2 arguments (tag + cacheLife) | | **Node.js** | 18.x+ | **20.9+** required | | **React** | 18.x | **19.2+** required |

**Quick Fix for Async Params**:

// ✅ Next.js 16 pattern
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  return <div>{id}</div>
}

**Codemod**: `bunx @next/codemod@canary upgrade latest`

**See**: `references/next-16-migration-guide.md` for complete migration guide with examples.

---

Cache Components & Caching APIs

"use cache" Directive (NEW in Next.js 16)

'use cache'

export async function BlogPosts() {
  const posts = await db.posts.findMany()
  return posts.map(post => <article key={post.id}>{post.title}</article>)
}

Caching APIs Summary

| API | Purpose | Example | |-----|---------|---------| | `"use cache"` | Opt-in component/function caching | `'use cache'` at top | | `revalidateTag()` | Invalidate by tag | `revalidateTag('posts', 'max')` | | `updateTag()` | Update cache without revalidation | `updateTag('posts', newData)` | | `refresh()` | Refresh current page | `refresh()` | | `revalidatePath()` | Invalidate by path | `revalidatePath('/posts')` |

PPR (Partial Prerendering)

// next.config.ts
const