nextjs

Next.js App Router - Production Patterns

Version: Next.js 16.0.0 React Version: 19.2.0 Node.js: 20.9+ Last Verified: 2025-10-24

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. [Proxy vs Middleware](#proxy-vs-middleware)
9. [Parallel Routes & Route Groups](#parallel-routes--route-groups)
10. [React 19.2 Features](#react-192-features)
11. [Metadata API](#metadata-api)
12. [Image & Font Optimization](#image--font-optimization)
13. [Performance Patterns](#performance-patterns)
14. [TypeScript Configuration](#typescript-configuration)
15. [Common Errors & Solutions](#common-errors--solutions)
16. [Templates Reference](#templates-reference)
17. [Additional Resources](#additional-resources)

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)
• Font optimization (next/font patterns)
• Turbopack configuration (stable and default in Next.js 16)
• Performance optimization (lazy loading, code splitting, PPR, ISR)
• TypeScript configuration (strict mode, path aliases)

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, 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
• 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)
• auth-js: For Auth.js (NextAuth) integration (composable with this skill)

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.

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 response
}

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

Note: middleware.ts still works in Next.js 16 but is deprecated. Migrate to proxy.ts for future compatibility.

See Template: templates/proxy-migration.ts See Reference: references/proxy-vs-middleware.md

3. Parallel Routes Require default.js (BREAKING)

Breaking Change: Parallel routes now require explicit default.js files. Without them, routes will fail during soft navigation.

Structure:

app/
├── @auth/
│   ├── login/
│   │   └── page.tsx
│   └── default.tsx    ← REQUIRED in Next.js 16
├── @dashboard/
│   ├── overview/
│   │   └── page.tsx
│   └── default.tsx    ← REQUIRED in Next.js 16
└── layout.tsx

Layout:

// app/layout.tsx
export default function Layout({
  children,
  auth,
  dashboard,
}: {
  children: React.ReactNode
  auth: React.ReactNode
  dashboard: React.ReactNode
}) {
  return (
    <html>
      <body>
        {auth}
        {dashboard}
        {children}
      </body>
    </html>
  )
}

Default Fallback (REQUIRED):

// app/@auth/default.tsx
export default function AuthDefault() {
  return null // or <Skeleton /> or redirect
}

// app/@dashboard/default.tsx
export d