Next.js App Router - Production Patterns

---

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

• 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

• 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

• 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)

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

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

---

Next.js 16.1 Updates (December 2025)

• 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

1. Async Route Parameters (BREAKING)

Copy
// ❌ 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>
}

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

Copy
// ❌ 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
}

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

Copy
// 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>;
}

---

2. Middleware → Proxy Migration (BREAKING)

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

Copy
// 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*',
}

---

3. Parallel Routes Require default.js (BREAKING)

Copy
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 default function DashboardDefault() {
  return null
}

---

4. Removed Features (BREAKING)

1. AMP Support - Entirely removed. Migrate to standard pages.
2. next lint command - Use ESLint or Biome directly.
3. serverRuntimeConfig and publicRuntimeConfig - Use environment variables instead.
4. experimental.ppr flag - Evolved into Cache Components. Use "use cache" directive.
5. Automatic scroll-behavior: smooth - Add manually if needed.
6. Node.js 18 support - Minimum version is now 20.9+.

• AMP: Convert AMP pages to standard pages or use separate AMP implementation.
• Linting: Run npx eslint . or npx biome lint . directly.
• Config: Replace serverRuntimeConfig with process.env.VARIABLE.
• PPR: Migrate from experimental.ppr to "use cache" directive (see Cache Components section).

---

5. Version Requirements (BREAKING)

• Node.js: 20.9+ (Node.js 18 no longer supported)
• TypeScript: 5.1+ (if using TypeScript)
• React: 19.2+ (automatically installed with Next.js 16)
• Browsers: Chrome 111+, Safari 16.4+, Firefox 109+, Edge 111+

Copy
node --version    # Should be 20.9+
npm --version     # Should be 10+
npx next --version # Should be 16.0.0+
`**Upgrade Node.js**:`
# Using nvm
nvm install 20
nvm use 20
nvm alias default 20

# Using Homebrew (macOS)
brew install node@20

# Using apt (Ubuntu/Debian)
sudo apt update
sudo apt install nodejs npm

---

6. Image Defaults Changed (BREAKING)

• Images cache longer (4 hours vs 60 seconds)
• Fewer image sizes generated (smaller builds, but less granular)
• Single quality (75) generated instead of multiple

Copy
// next.config.ts
import type { NextConfig } from 'next'

const config: NextConfig = {
  images: {
    minimumCacheTTL: 60, // Revert to 60 seconds
    deviceSizes: [640, 750, 828, 1080, 1200, 1920], // Add larger sizes
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384], // Restore old sizes
    formats: ['image/webp'], // Default
  },
}

export default config

---

Cache Components & Caching APIs

1. Overview

• Next.js 15: Implicit caching (all Server Components cached by default)
• Next.js 16: Opt-in caching with "use cache" directive

• Component-level caching (cache specific components, not entire pages)
• Function-level caching (cache expensive computations)
• Page-level caching (cache entire pages selectively)
• Partial Prerendering (PPR) - Cache static parts, render dynamic parts on-demand

---

2. "use cache" Directive

Copy
// app/components/expensive-component.tsx
'use cache'

export async function ExpensiveComponent() {
  const data = await fetch('https://api.example.com/data')
  const json = await data.json()

  return (
    <div>
      <h1>{json.title}</h1>
      <p>{json.description}</p>
    </div>
  )
}
`**Function-level caching**:`
// lib/data.ts
'use cache'

export async function getExpensiveData(id: string) {
  const response = await fetch(`https://api.example.com/items/${id}`)
  return response.json()
}

// Usage in component
import { getExpensiveData } from '@/lib/data'

export async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const product = await getExpensiveData(id) // Cached

  return <div>{product.name}</div>
}
`**Page-level caching**:`
// app/blog/[slug]/page.tsx
'use cache'

export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts').then(r => r.json())
  return posts.map((post: { slug: string }) => ({ slug: post.slug }))
}

export default async function BlogPost({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const post = await fetch(`https://api.example.com/posts/${slug}`).then(r => r.json())

  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  )
}

---

3. Partial Prerendering (PPR)

Copy
// app/dashboard/page.tsx

// Static header (cached)
'use cache'
async function StaticHeader() {
  return <header>My App</header>
}

// Dynamic user info (not cached)
async function DynamicUserInfo() {
  const cookieStore = await cookies()
  const userId = cookieStore.get('userId')?.value
  const user = await fetch(`/api/users/${userId}`).then(r => r.json())

  return <div>Welcome, {user.name}</div>
}

// Page combines both
export default function Dashboard() {
  return (
    <div>
      <StaticHeader /> {/* Cached */}
      <DynamicUserInfo /> {/* Dynamic */}
    </div>
  )
}

• Page has both static and dynamic content
• Want to cache layout/header/footer but render user-specific content
• Need fast initial load (static parts) + personalization (dynamic parts)

---

4. revalidateTag() - Updated API

Copy
import { revalidateTag } from 'next/cache'

export async function updatePost(id: string) {
  await fetch(`/api/posts/${id}`, { method: 'PATCH' })
  revalidateTag('posts') // ❌ Only one argument in Next.js 15
}
`**After (Next.js 16)**:`
import { revalidateTag } from 'next/cache'

export async function updatePost(id: string) {
  await fetch(`/api/posts/${id}`, { method: 'PATCH' })
  revalidateTag('posts', 'max') // ✅ Second argument required in Next.js 16
}

• 'max' - Maximum staleness (recommended for most use cases)
• 'hours' - Stale after hours
• 'days' - Stale after days
• 'weeks' - Stale after weeks
• 'default' - Default cache behavior

Copy
revalidateTag('posts', {
  stale: 3600, // Stale after 1 hour (seconds)
  revalidate: 86400, // Revalidate every 24 hours (seconds)
  expire: false, // Never expire (optional)
})
`**Pattern in Server Actions**:`
'use server'

import { revalidateTag } from 'next/cache'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  const content = formData.get('content') as string

  await fetch('/api/posts', {
    method: 'POST',
    body: JSON.stringify({ title, content }),
  })

  revalidateTag('posts', 'max') // ✅ Revalidate with max staleness
}

---

5. updateTag() - NEW API (Server Actions Only)

• Expires cache immediately
• Refreshes data within the same request
• Shows updated data right after mutation (no stale data)

• revalidateTag(): Stale-while-revalidate (shows stale data, revalidates in background)
• updateTag(): Immediate refresh (expires cache, fetches fresh data in same request)

Copy
'use server'

import { updateTag } from 'next/cache'

export async function updateUserProfile(formData: FormData) {
  const name = formData.get('name') as string
  const email = formData.get('email') as string

  // Update database
  await db.users.update({ name, email })

  // Immediately refresh cache (read-your-writes)
  updateTag('user-profile')

  // User sees updated data immediately (no stale data)
}

• updateTag(): User settings, profile updates, critical mutations (immediate feedback)
• revalidateTag(): Blog posts, product listings, non-critical updates (background revalidation)

---

6. refresh() - NEW API (Server Actions Only)

• Refresh dynamic data without affecting cached data
• Complement router.refresh() on server side

Copy
'use server'

import { refresh } from 'next/cache'

export async function refreshDashboard() {
  // Refresh uncached data (e.g., real-time metrics)
  refresh()

  // Cached data (e.g., static header) remains cached
}

• refresh(): Only refreshes uncached data
• revalidateTag(): Revalidates specific tagged data (stale-while-revalidate)
• updateTag(): Immediately expires and refreshes specific tagged data

---

---

Route Handlers (Next.js 16 Updates)

Async Params in Route Handlers (BREAKING)

Copy
// app/api/posts/[id]/route.ts
import { NextResponse } from 'next/server'
import { headers } from 'next/headers'

export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params // ✅ Await params in Next.js 16
  const headersList = await headers() // ✅ Await headers in Next.js 16

  const post = await db.posts.findUnique({ where: { id } })

  return NextResponse.json(post)
}

---

Proxy vs Middleware

Why the Change?

• middleware.ts: Runs on Edge runtime (limited Node.js APIs)
• proxy.ts: Runs on Node.js runtime (full Node.js APIs)

Migration

Copy
// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // Check auth
  const token = request.cookies.get('token')

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }

  return NextResponse.next()
}

export const config = {
  matcher: '/dashboard/:path*',
}
`**After (proxy.ts)**:`
// proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // Check auth
  const token = request.cookies.get('token')

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }

  return NextResponse.next()
}

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

---

Parallel Routes - default.js Required (BREAKING)

Copy
app/
├── @modal/
│   ├── login/page.tsx
│   └── default.tsx  ← REQUIRED in Next.js 16
├── @feed/
│   ├── trending/page.tsx
│   └── default.tsx  ← REQUIRED in Next.js 16
└── layout.tsx
`**Default Files (REQUIRED)**:`
// app/@modal/default.tsx
export default function ModalDefault() {
  return null // or <Skeleton /> or redirect
}

Copy
// app/@modal/[...catchAll]/page.tsx
export default function CatchAll() {
  return null;
}

// OR use catch-all in default.tsx
// app/@modal/default.tsx
export default function ModalDefault({ params }: { params: { catchAll?: string[] } }) {
  return null; // Handles all unmatched routes
}

---

React 19.2 Features

1. View Transitions

Copy
'use client'

import { useRouter } from 'next/navigation'
import { startTransition } from 'react'

export function NavigationLink({ href, children }: { href: string; children: React.ReactNode }) {
  const router = useRouter()

  function handleClick(e: React.MouseEvent) {
    e.preventDefault()

    // Wrap navigation in startTransition for View Transitions
    startTransition(() => {
      router.push(href)
    })
  }

  return <a href={href} onClick={handleClick}>{children}</a>
}
`**With CSS View Transitions API**:`
/* app/globals.css */
@view-transition {
  navigation: auto;
}

/* Animate elements with view-transition-name */
.page-title {
  view-transition-name: page-title;
}

---

2. useEffectEvent() (Experimental)

Copy
'use client'

import { useEffect, experimental_useEffectEvent as useEffectEvent } from 'react'

export function ChatRoom({ roomId }: { roomId: string }) {
  const onConnected = useEffectEvent(() => {
    console.log('Connected to room:', roomId)
  })

  useEffect(() => {
    const connection = connectToRoom(roomId)
    onConnected() // Non-reactive callback

    return () => connection.disconnect()
  }, [roomId]) // Only re-run when roomId changes

  return <div>Chat Room {roomId}</div>
}

---

3. React Compiler (Stable)

Copy
import type { NextConfig } from 'next'

const config: NextConfig = {
  experimental: {
    reactCompiler: true,
  },
}

export default config
`**Install Plugin**:`
npm install babel-plugin-react-compiler
`**Example** (no manual memoization needed):`
'use client'

export function ExpensiveList({ items }: { items: string[] }) {
  // React Compiler automatically memoizes this
  const filteredItems = items.filter(item => item.length > 3)

  return (
    <ul>
      {filteredItems.map(item => (
        <li key={item}>{item}</li>
      ))}
    </ul>
  )
}

---

Turbopack (Stable in Next.js 16)

• 2–5× faster production builds
• Up to 10× faster Fast Refresh

Copy
// next.config.ts
import type { NextConfig } from 'next'

const config: NextConfig = {
  experimental: {
    turbopack: {
      fileSystemCaching: true, // Beta: Persist cache between runs
    },
  },
}

export default config

---

Turbopack Production Limitations (as of Next.js 16.1)

1. Prisma Incompatibility

Copy
# Use webpack for production builds
npm run build -- --webpack
`Or in `next.config.ts`:`
const config: NextConfig = {
  experimental: {
    turbo: false, // Disable Turbopack for production
  },
};

---

2. Source Maps Security Risk

Copy
// next.config.ts
const config: NextConfig = {
  productionBrowserSourceMaps: false, // Disable source maps
};
`Or exclude `.map` files in deployment:`
# .vercelignore or similar
*.map

---

3. External Module Hash Mismatches (Monorepos)

• Build succeeds locally but fails in CI/CD
• Hash mismatches between bundled references and actual module files

Copy
// next.config.ts
const config: NextConfig = {
  experimental: {
    serverExternalPackages: ['package-name'], // Explicitly externalize packages
  },
};

---

4. Bundle Size Differences (Community-sourced)

---

Common Errors & Solutions

1. Error: params is a Promise

Copy
// ❌ Before
export default function Page({ params }: { params: { id: string } }) {
  const id = params.id
}

// ✅ After
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
}

---

2. Error: searchParams is a Promise

Copy
// ❌ Before
export default function Page({ searchParams }: { searchParams: { query: string } }) {
  const query = searchParams.query
}

// ✅ After
export default async function Page({ searchParams }: { searchParams: Promise<{ query: string }> }) {
  const { query } = await searchParams
}

---

3. Error: cookies() requires await

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

export function MyComponent() {
  const cookieStore = cookies()
}

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

export async function MyComponent() {
  const cookieStore = await cookies()
}

---

4. Error: Parallel route missing default.js

Copy
// app/@modal/default.tsx
export default function ModalDefault() {
  return null
}

---

5. Error: revalidateTag() requires 2 arguments

Copy
// ❌ Before
revalidateTag('posts')

// ✅ After
revalidateTag('posts', 'max')

---

6. Error: Cannot use React hooks in Server Component

Copy
// ✅ Add 'use client' at the top
'use client'

import { useState } from 'react'

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

---

7. Error: middleware.ts is deprecated

Copy
// Rename: middleware.ts → proxy.ts
// Rename function: middleware → proxy

export function proxy(request: NextRequest) {
  // Same logic
}

---

8. Error: Turbopack build failure

---

9. Error: Invalid next/image src

---

10. Error: Cannot import Server Component into Client Component

---

11. Error: generateStaticParams not working

---

12. Error: fetch() not caching

---

13. Error: Route collision with Route Groups

---

14. Error: Metadata not updating

---

15. Error: next/font font not loading

---

16. Error: Environment variables not available in browser

---

17. Error: Server Action not found

---

18. Error: TypeScript path alias not working

---

19. Error: Client-side navigation throttled with multiple redirects

• Works in next dev (development mode)
• Works with direct URL access (full page load)
• Fails with client-side navigation via <Link> in production build
• Prefetch causes infinite redirect loop

---

20. Error: Cache Components fail with i18n dynamic segments

---

21. Error: instanceof fails for custom error classes in Server Components

---

22. Error: TypeScript doesn't catch non-serializable props to Client Components

---

23. Error: Turbopack production build fails with Prisma

---

24. Error: Turbopack exposes source code via source maps

---

25. Error: Module not found in production (Turbopack monorepo)

• Build succeeds locally but fails in CI/CD
• Hash mismatches between bundled references and actual module files

---

---

Templates & Resources

• app-router-async-params.tsx - Async params migration patterns
• parallel-routes-with-default.tsx - Required default.js files
• cache-component-use-cache.tsx - Cache Components with "use cache"
• revalidate-tag-cache-life.ts - Updated revalidateTag() with cacheLife
• server-action-update-tag.ts - updateTag() for read-your-writes
• proxy-migration.ts - Migrate from middleware.ts to proxy.ts
• view-transitions-react-19.tsx - React 19.2 View Transitions
• next.config.ts - Next.js 16 configuration

• next-16-migration-guide.md - Complete Next.js 15→16 migration guide
• cache-components-guide.md - Cache Components deep dive
• proxy-vs-middleware.md - Proxy.ts vs middleware.ts
• async-route-params.md - Async params breaking change details
• react-19-integration.md - React 19.2 features in Next.js 16
• top-errors.md - 18+ common errors with solutions

• Next.js 16 Blog: https://nextjs.org/blog/next-16
• Next.js Docs: https://nextjs.org/docs
• Context7 MCP: /websites/nextjs for latest reference

---

Version Compatibility

---

Token Efficiency

• Read Next.js 16 migration guide: ~5k tokens
• Read App Router docs: ~8k tokens
• Read Server Actions docs: ~4k tokens
• Read Metadata API docs: ~3k tokens
• Trial-and-error fixes: ~8k tokens
• Total: ~28k tokens

• Load skill: ~8k tokens
• Use templates: ~2k tokens
• Total: ~10k tokens
• Savings: ~18k tokens (~64%)

---

Maintenance

• Next.js major/minor releases
• React major releases
• Breaking changes in APIs
• New Turbopack features

Copy
cd skills/nextjs
./scripts/check-versions.sh

---