Next.js App Router - Production Patterns

Version: Next.js 16.1.1 React Version: 19.2.3 Node.js: 20.9+ Last Verified: 2026-01-09

---

Table of Contents

1. When to Use This Skill
2. When NOT to Use This Skill
3. Security Advisories (December 2025)
4. Next.js 16.1 Updates
5. Next.js 16 Breaking Changes
6. Cache Components & Caching APIs
7. Route Handlers (Next.js 16 Updates)
8. Proxy vs Middleware
9. Parallel Routes - default.js Required
10. React 19.2 Features
11. Turbopack (Stable in Next.js 16)
12. Common Errors & Solutions
13. Templates & Resources

---

When to Use This Skill

Focus: Next.js 16 breaking changes and knowledge gaps (December 2024+).

Use this skill when you need:

• Next.js 16 breaking changes (async params, proxy.ts, parallel routes default.js, removed features)
• 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 (avoid breaking change errors)
• Async route params (params, searchParams, cookies(), headers() now async)
• Parallel routes with default.js (REQUIRED in Next.js 16)
• React 19.2 features (View Transitions, useEffectEvent(), React Compiler)
• Turbopack (stable and default in Next.js 16)
• Image defaults changed (TTL, sizes, qualities in Next.js 16)
• Error prevention (25 documented Next.js 16 errors with solutions)

---

When NOT to Use This Skill

Do NOT use this skill for:

• Cloudflare Workers deployment → Use cloudflare-nextjs skill instead
• Pages Router patterns → This skill covers App Router ONLY (Pages Router is legacy)
• Authentication libraries → Use clerk-auth, better-auth, 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
• Vercel-specific features → Refer to Vercel platform documentation
• Next.js Enterprise features (ISR, DPR) → Refer to Next.js Enterprise docs
• Deployment configuration → Use platform-specific deployment skills

Relationship with Other Skills:

• cloudflare-nextjs: For deploying Next.js to Cloudflare Workers (use BOTH skills together if deploying to Cloudflare)
• tailwind-v4-shadcn: For Tailwind v4 + shadcn/ui setup (composable with this skill)
• clerk-auth: For Clerk authentication in Next.js (composable with this skill)
• better-auth: For Better Auth integration (composable with this skill)

---

Security Advisories (December 2025)

CRITICAL: Three security vulnerabilities were disclosed in December 2025 affecting Next.js with React Server Components:

CVE	Severity	Affected	Description
CVE-2025-66478	CRITICAL (10.0)	15.x, 16.x	Server Component arbitrary code execution
CVE-2025-55184	HIGH	13.x-16.x	Denial of Service via malformed request
CVE-2025-55183	MEDIUM	13.x-16.x	Source code exposure in error responses

Action Required: Upgrade to Next.js 16.1.1 or later immediately.

npm update next
# Verify: npm list next should show 16.1.1+

References:

• https://nextjs.org/security
• https://github.com/vercel/next.js/security/advisories

---

Next.js 16.1 Updates (December 2025)

New in 16.1:

• Turbopack File System Caching (STABLE): Now enabled by default in development
• Next.js Bundle Analyzer: New experimental feature for bundle analysis
• Improved Debugging: Enhanced next dev --inspect support
• Security Fixes: Addresses CVE-2025-66478, CVE-2025-55184, CVE-2025-55183

---

Next.js 16 Breaking Changes

IMPORTANT: Next.js 16 introduces multiple breaking changes. Read this section carefully if migrating from Next.js 15 or earlier.

1. Async Route Parameters (BREAKING)

Breaking Change: params, searchParams, cookies(), headers(), draftMode() are now async and must be awaited.

Before (Next.js 15):

// ❌ This no longer works in Next.js 16
export default function Page({ params, searchParams }: {
  params: { slug: string }
  searchParams: { query: string }
}) {
  const slug = params.slug // ❌ Error: params is a Promise
  const query = searchParams.query // ❌ Error: searchParams is a Promise
  return <div>{slug}</div>
}

After (Next.js 16):

// ✅ Correct: await params and searchParams
export default async function Page({ params, searchParams }: {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ query: string }>
}) {
  const { slug } = await params // ✅ Await the promise
  const { query } = await searchParams // ✅ Await the promise
  return <div>{slug}</div>
}

Applies to:

• params in pages, layouts, route handlers
• searchParams in pages
• cookies() from next/headers
• headers() from next/headers
• draftMode() from next/headers

Migration:

// ❌ Before
import { cookies, headers } from 'next/headers'

export function MyComponent() {
  const cookieStore = cookies() // ❌ Sync access
  const headersList = headers() // ❌ Sync access
}

// ✅ After
import { cookies, headers } from 'next/headers'

export async function MyComponent() {
  const cookieStore = await cookies() // ✅ Async access
  const headersList = await headers() // ✅ Async access
}

Codemod: Run npx @next/codemod@canary upgrade latest to automatically migrate.

Codemod Limitations (Community-sourced): The official codemod handles ~80% of async API migrations but misses edge cases:

• Async APIs accessed in custom hooks
• Conditional logic accessing params
• Components imported from external packages
• Complex server actions with multiple async calls

After running the codemod, search for @next-codemod-error comments marking places it couldn't auto-fix.

Manual Migration for Client Components:

// For client components, use React.use() to unwrap promises
'use client';

import { use } from 'react';

export default function ClientComponent({
  params
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = use(params); // Unwrap Promise in client
  return <div>{id}</div>;
}

See Template: templates/app-router-async-params.tsx

---

2. Middleware → Proxy Migration (BREAKING)

Breaking Change: middleware.ts is deprecated in Next.js 16. Use proxy.ts instead.

Why the Change: proxy.ts makes the network boundary explicit by running on Node.js runtime (not Edge runtime). This provides better clarity between edge middleware and server-side proxies.

Migration Steps:

1. Rename file: middleware.ts → proxy.ts
2. Rename function: middleware → proxy
3. Update config: matcher → config.matcher (same syntax)

Before (Next.js 15):

// middleware.ts ❌ Deprecated in Next.js 16
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const response = NextResponse.next()
  response.headers.set('x-custom-header', 'value')
  return response
}

export const config = {
  matcher: '/api/:path*',
}

After (Next.js 16):

// proxy.ts ✅ New in Next.js 16
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  const response = NextResponse.next()
  response.headers.set('x-custom-header', 'value')
  return r