Skip to main content
skill CX Codex

Next.js 16 skill for Claude Code: App Router, Server Components, SSR · secondsky

Skill for Next.js 16 and React 19.2 with App Router, Server Components, Server Actions, and caching patterns. Handles migration from version 15, async params errors, and Partial Prerendering setup.

MIT 299 installs ★ 250 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add secondsky/claude-skills --skill nextjs -a claude-code
Open on GitHub

What nextjs does

Covers App Router, Server Components, Server Actions, Cache Components with the "use cache" directive, and caching APIs (revalidateTag(), updateTag(), refresh()). Includes patterns for Route Handlers, Suspense, parallel routes, SEO metadata, and image optimization.

Documents eight critical breaking changes in Next.js 16: async params and headers(), middleware.ts renamed to proxy.ts, required default.js for parallel routes, opt-in caching instead of automatic. Requires Node.js 20.9+ and React 19.2+.

Use this skill when working with App Router, Server Components, or upgrading from Next.js 15. Not for Pages Router, Cloudflare Workers deployment (use cloudflare-nextjs instead), or when you need auth libraries and ORMs—those have dedicated skills.

What it helps with

  • understand async params and async headers in Next.js 16
  • set up caching with "use cache" and revalidateTag()
  • migrate middleware.ts to proxy.ts
  • configure parallel routes with required default.js
  • implement Suspense and streaming SSR

Example prompts for the agent

  • Show me how to use async params correctly in layout.tsx for Next.js 16
  • Help me migrate from middleware.ts to proxy.ts
  • Write a Server Component with "use cache" for fetching posts from the database

How to install nextjs

1Skills CLI (Vercel)

npx skills add secondsky/claude-skills --skill nextjs -a claude-code

2Manually: put the files in place

~/.claude/skills/nextjs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nextjs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about nextjs

How do I install the nextjs skill for Claude Code?

Run npx skills add secondsky/claude-skills --skill nextjs -a claude-code, then check the guide at ~/.claude/skills/nextjs/SKILL.md.

What does the nextjs skill do?

It explains Next.js 16 patterns: App Router, Server Components, Server Actions, caching, and upgrade paths from version 15. Includes breaking changes reference and code examples.

What Node.js version is required?

Node.js 20.9 or later. React 19.2+ is mandatory for Next.js 16 compatibility.

Source text

SKILL.md · MIT
---
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**:
```typescript
// ✅ 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)

```typescript
'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)

```typescript
// next.config.ts
const config = { experimental: { ppr: true } }

// page.tsx
export const experimental_ppr = true

export default function Page() {
  return (
    <>
      <StaticHeader />
      <Suspense fallback={<Skeleton />}>
        <DynamicContent />
      </Suspense>
    </>
  )
}
```

**See**: `references/caching-apis.md` for complete caching API reference with ISR, tag-based revalidation, and advanced patterns.

---

## Server Components

Server Components are the **default** in App Router. They run on the server and can fetch data, access databases, and keep logic server-side.

```typescript
// app/posts/page.tsx (Server Component by default)
export default async function PostsPage() {
  const posts = await db.posts.findMany()
  return <div>{posts.map(p => <article key={p.id}>{p.title}</article>)}</div>
}
```

### Streaming with Suspense

```typescript
import { Suspense } from 'react'

export default function Page() {
  return (
    <div>
      <Header />
      <Suspense fallback={<Skeleton />}>
        <Posts />
      </Suspense>
    </div>
  )
}
```

### Server vs Client Components

| Server Components | Client Components |
|-------------------|-------------------|
| Data fetching, DB access | Interactivity (onClick) |
| Sensitive logic | React hooks (useState) |
| Large dependencies | Browser APIs |
| Static content | Real-time updates |

**Client Component** (requires `'use client'`):
```typescript
'use client'
import { useState } from 'react'
export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```

---

## Server Actions

Server Actions are async functions that run on the server, callable from Client or Server Components.

### Basic Server Action

```typescript
// app/actions.ts
'use server'

import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  await db.posts.create({ data: { title } })
  revalidatePath('/posts')
}
```

### Form Handling

```typescript
// Server Component Form (simplest)
import { createPost } from './actions'

export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <button type="submit">Create</button>
    </form>
  )
}
```

### Available Patterns

| Pattern | Use Case | Reference |
|---------|----------|-----------|
| Client Form with Loading | useFormState + useFormStatus | `templates/server-action-form.tsx` |
| Error Handling | Return { error } or { success } | `references/server-actions-patterns.md` |
| Optimistic Updates | useOptimistic hook | `references/server-actions-patterns.md` |
| File Upload | FormData + blob storage | `references/server-actions-patterns.md` |
| Redirect After Action | redirect() function | `references/server-actions-patterns.md` |

**See**: `references/server-actions-patterns.md` for error handling, optimistic updates, file uploads, and advanced patterns.

---

## Route Handlers

Route Handlers are the App Router equivalent of API Routes.

```typescript
// app/api/posts/route.ts
export async function GET(request: Request) {
  const posts = await db.posts.findMany()
  return Response.json({ posts })
}

export async function POST(request: Request) {
  const body = await request.json()
  const post = await db.posts.create({ data: body })
  return Response.json({ post }, { status: 201 })
}
```

**Dynamic Routes** (with async params):
```typescript
// app/api/posts/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params // Await in Next.js 16
  const post = await db.posts.findUnique({ where: { id } })
  return post ? Response.json({ post }) : Response.json({ error: 'Not found' }, { status: 404 })
}
```

**See**: `templates/route-handler-api.ts` for search params, webhooks, and streaming patterns.

---

## React 19.2 Features

| Feature | Usage |
|---------|-------|
| **React Compiler** | `experimental: { reactCompiler: true }` - Auto-memoization |
| **View Transitions** | `useTransition()` + `router.push()` |
| **useEffectEvent** | Stable event handlers without deps |

---

## Metadata API

```typescript
// Static metadata
export const metadata: Metadata = {
  title: 'My Blog',
  description: 'A blog about Next.js',
  openGraph: { title: 'My Blog', images: ['/og-image.jpg'] },
}

// Dynamic metadata (await params in Next.js 16)
export async function generateMetadata({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const post = await db.posts.findUnique({ where: { id } })
  return { title: post.title, description: post.excerpt }
}
```

---

## Image & Font Optimization

```typescript
// next/image
import Image from 'next/image'
<Image src="/profile.jpg" alt="Profile" width={500} height={500} priority />

// next/font
import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
<html className={inter.variable}>
```

**Remote images**: Configure `images.remotePatterns` in `next.config.ts`.

---

## Top 5 Critical Errors

### Error 1: `params` is a Promise

**Error**: `Type 'Promise<{ id: string }>' is not assignable to type '{ id: string }'`

**Solution**: Await params in Next.js 16:
```typescript
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
}
```

---

### Error 2: `middleware.ts` is deprecated

**Warning**: `middleware.ts is deprecated. Use proxy.ts instead.`

**Solution**: Rename file and function:
```typescript
// Rename: middleware.ts → proxy.ts
// Rename function: middleware → proxy
export function proxy(request: NextRequest) {
  // Same logic
}
```

---

### Error 3: Parallel route missing `default.js`

**Error**: `Parallel route @modal was matched but no default.js was found`

**Solution**: Add default.tsx:
```typescript
// app/@modal/default.tsx
export default function ModalDefault() {
  return null
}
```

---

### Error 4: Cannot use React hooks in Server Component

**Error**: `You're importing a component that needs useState. It only works in a Client Component`

**Solution**: Add `'use client'`:
```typescript
'use client'

import { useState } from 'react'

export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```

---

### Error 5: `fetch()` not caching

**Cause**: Next.js 16 uses opt-in caching with `"use cache"`.

**Solution**: Add `"use cache"` directive:
```typescript
'use cache'

export async function getPosts() {
  const response = await fetch('/api/posts')
  return response.json()
}
```

---

**See All 18 Errors**: `references/error-catalog.md`

---

## Performance Patterns

| Pattern | Usage |
|---------|-------|
| **Lazy Loading** | `const HeavyComp = dynamic(() => import('./Heavy'), { ssr: false })` |
| **Code Splitting** | Automatic per route - each `page.tsx` gets own bundle |
| **Turbopack** | Default in Next.js 16, opt out with `--webpack` flag |
| **PPR** | `experimental: { ppr: true }` + `<Suspense>` boundaries |

---

## TypeScript Configuration

```json
{
  "compilerOptions": {
    "strict": true,
    "baseUrl": ".",
    "paths": { "@/*": ["./*"] }
  }
}
```

---

## When to Load References

| Reference | Load When... |
|-----------|--------------|
| `next-16-migration-guide.md` | Migrating from Next.js 15, async params errors, proxy.ts setup |
| `server-actions-patterns.md` | Error handling, optimistic updates, file uploads, advanced forms |
| `caching-apis.md` | ISR, tag-based revalidation, updateTag(), refresh(), PPR details |
| `error-catalog.md` | Debugging any Next.js error, comprehensive error solutions |
| `top-errors.md` | Quick fixes for the 5 most common Next.js errors |

---

## Bundled Resources

| Type | Files |
|------|-------|
| **References** | `error-catalog.md`, `top-errors.md`, `next-16-migration-guide.md`, `server-actions-patterns.md`, `caching-apis.md` |
| **Templates** | `async-params-page.tsx`, `server-action-form.tsx`, `route-handler-api.ts`, `cache-component-use-cache.tsx`, `parallel-routes-with-default.tsx`, `proxy-migration.ts` |

---

## Related Skills

| Skill | Purpose |
|-------|---------|
| `cloudflare-nextjs` | Deploy to Cloudflare Workers via the OpenNext adapter (`@opennextjs/cloudflare`) |
| `tailwind-v4-shadcn` | Styling |
| `clerk-auth` | Authentication |
| `drizzle-orm-d1` | Database |
| `react-hook-form-zod` | Forms |
| `zustand-state-management` | Client state |

**Official Docs**: https://nextjs.org/docs | **App Router**: https://nextjs.org/docs/app

---

**Version**: Next.js 16.2.0 | React 19.2.0 | Node.js 20.9+ | TypeScript 5.9+
**Production Tested**: E-commerce, SaaS, content sites | **Token Savings**: 65-70%

© Claude Skills Maintainers · MIT · secondsky/claude-skills

Similar skills

All skills for Frontend and UI →

nextjs by other authors comes first.

nextjs official Vercel Labs Guidance for building and debugging Next.js App Router projects. Use it to work through routing, Server Components, data fetching, and rendering choices. CX Codex GP ChatGPT +1 50installs nextjs pproenca This skill guides Next.js 16 App Router work, from caching and Server Components to routing and codebase reviews. CX Codex +1 1,200installs nextjs PyModel Skill for Claude Code, Codex, and Cursor enforces Next.js 16 App Router standards. It guides caching strategies, server components, and routing patterns. CX Codex +1 621installs nextjs bobmatnyc Maps Next.js environment variables across .env* files, shows which one wins, and covers Vercel deployment. CX Codex +1 212installs nextjs ulpi-io Guides coding agents through Next.js App Router tasks while respecting the project's installed framework release and internal architecture. CX Codex +1 182installs nextjs-app-router-patterns Seth Hobson This skill covers Next.js App Router patterns for rendering, routing, and data fetching. Use it when starting an App Router project or moving from Pages Router. CX Codex +1 32,529installs nextjs-development manutej nextjs-development — a reference skill for building modern Next.js applications in the app directory. It guides coding assistants through Server Components, routing, and cache revalidation. CX Codex +1 475installs nextjs-expert BuildWithClaude Community The nextjs-expert plugin for Claude Code and Cursor provides five skills and three slash commands for the Next.js App Router, supporting page and API development in Next.js 15. ★ 3,785repo stars nextjs-app-router-expert curiositech The nextjs-app-router-expert skill guides Next.js 14/15 App Router work, from route design to data loading. Use it when building or debugging server-rendered React features. CX Codex +1 176installs nextjs-architecture-expert davila7 nextjs-architecture-expert — a Claude subagent for Next.js architecture: App Router, Server Components, Pages Router migration and performance work. CX Codex 4,935installs nextjs-cache-architecture mohamed-hossam1 nextjs-cache-architecture structures caching architecture in Next.js 16+ App Router projects. It sets up the "use cache" directive, a typed tag registry, and Suspense boundaries. CX Codex +1 5,100installs

From the same set138

The whole set →
cloudflare-r2 Skill for working with Cloudflare R2, an S3-compatible object storage. Manages buckets, uploads, CORS and presigned URLs — everything needed to handle files in the cloud. CX Codex +1 316installs cloudflare-workers-migration cloudflare-workers-migration — a skill for porting applications to Cloudflare Workers from AWS Lambda, Vercel, Express and Node.js. Adapts handlers, middleware and environment variables to Web APIs. CX Codex +1 316installs tanstack-query This skill guides Claude Code through TanStack Query v5 for fetching, caching, mutations, and v4 migration issues in React projects. CX Codex +1 314installs zustand-state-management zustand-state-management guides agent setup of Zustand v5 stores for React 18+ and TypeScript 5+. Fixes Next.js hydration mismatches and prevents selector re-render loops. CX Codex +1 301installs feature-dev The feature-dev skill guides feature work through seven phases, from codebase discovery to review. Use it for multi-file changes and unclear architecture decisions. CX Codex +1 294installs cloudflare-nextjs The cloudflare-nextjs skill guides Next.js deployments to Cloudflare Workers with OpenNext. Use it to migrate a project or troubleshoot Workers-specific configuration and runtime issues. CX Codex +1 267installs cloudflare-turnstile cloudflare-turnstile is a Claude Code skill for adding Turnstile and checking tokens on the server. It activates for bot protection work, widget errors, and CSP or token validation failures. CX Codex +1 261installs base-ui-react base-ui-react is a Claude Code skill for building MUI Base UI interfaces, configuring accessible components and popup positioning, and migrating from Radix UI. CX Codex +1 259installs

Project sponsors

Companies that keep this analytics open