Initial commit

2025-11-30 08:25:04 +08:00
commit 331f882756
14 changed files with 5182 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
 {
  "name": "nextjs",
  "description": "Build Next.js 16 apps with App Router, Server Components/Actions, Cache Components (use cache), and async route params. Includes proxy.ts (replaces middleware.ts) and React 19.2. Use when: building Next.js 16 projects, or troubleshooting async params (Promise types), use cache directives, parallel route 404s (missing default.js), or proxy.ts CORS.",
  "version": "1.0.0",
  "author": {
    "name": "Jeremy Dawes",
    "email": "jeremy@jezweb.net"
  },
  "skills": [
    "./"
  ]
 }
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
 # nextjs
 Build Next.js 16 apps with App Router, Server Components/Actions, Cache Components (use cache), and async route params. Includes proxy.ts (replaces middleware.ts) and React 19.2. Use when: building Next.js 16 projects, or troubleshooting async params (Promise types), use cache directives, parallel route 404s (missing default.js), or proxy.ts CORS.
--- a/SKILL.md
+++ b/SKILL.md
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,85 @@
 {
  "$schema": "internal://schemas/plugin.lock.v1.json",
  "pluginId": "gh:jezweb/claude-skills:skills/nextjs",
  "normalized": {
    "repo": null,
    "ref": "refs/tags/v20251128.0",
    "commit": "7752a82e83393fe7be5bce05d0911b6498c93050",
    "treeHash": "751d0e9f13f37b25b60eb7bd37981fed86ad120f2e150e053f240a521b9b9e85",
    "generatedAt": "2025-11-28T10:18:59.854318Z",
    "toolVersion": "publish_plugins.py@0.2.0"
  },
  "origin": {
    "remote": "git@github.com:zhongweili/42plugin-data.git",
    "branch": "master",
    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
  },
  "manifest": {
    "name": "nextjs",
    "description": "Build Next.js 16 apps with App Router, Server Components/Actions, Cache Components (use cache), and async route params. Includes proxy.ts (replaces middleware.ts) and React 19.2. Use when: building Next.js 16 projects, or troubleshooting async params (Promise types), use cache directives, parallel route 404s (missing default.js), or proxy.ts CORS.",
    "version": "1.0.0"
  },
  "content": {
    "files": [
      {
        "path": "README.md",
        "sha256": "291f3e1170756b73e817589cfd801423a4db65b30f736b90173f1b0464d3c688"
      },
      {
        "path": "SKILL.md",
        "sha256": "0d274baa9085ed5ded3c5fca56c8498352197345eb18136d125e05e1ecee9164"
      },
      {
        "path": "references/next-16-migration-guide.md",
        "sha256": "b13cb9e7d265f5eeb49f4d25bbc3db9f4afaec519adfb3661a94e811fd41d4a7"
      },
      {
        "path": "references/top-errors.md",
        "sha256": "fbc231577f65325a341578a53faa59bcefb0158ab39053d02b8245a09dd7ab05"
      },
      {
        "path": "scripts/check-versions.sh",
        "sha256": "81b37d00e6f3b91f2b9e411dd85f5f9681c95957eb951ed8d9da9da5914f5a70"
      },
      {
        "path": ".claude-plugin/plugin.json",
        "sha256": "c1c2ed4e43352267df00c2ba4037ec218053613a8bb4a8eb93130c2ad1bf6f8b"
      },
      {
        "path": "templates/server-actions-form.tsx",
        "sha256": "8b13071ca8c839e1e7a37792686a25853f43ecfdbb17cf4534c4489049ee57cb"
      },
      {
        "path": "templates/proxy-migration.ts",
        "sha256": "362c27846d847e2ebd01692e980f1b3c0b4bb4e1cff8f1fd98e6979ee59dbb3c"
      },
      {
        "path": "templates/route-handler-api.ts",
        "sha256": "be6533d939727add7e97aaebf6b91eed846a8c343b93f9a6b27c44019811036d"
      },
      {
        "path": "templates/package.json",
        "sha256": "298748ae5473db8d20cae62bba914fd6878f983cd2ebf0c55f6ae3a50b264853"
      },
      {
        "path": "templates/app-router-async-params.tsx",
        "sha256": "7630604e4d4d11e83a36b2337f833c286ef1381ca5217076a15db8ec32a856c5"
      },
      {
        "path": "templates/cache-component-use-cache.tsx",
        "sha256": "986256a04ebce7de7c624a5c5d0f5fd84fc2a590cc5600dfff18a97bae8eabae"
      },
      {
        "path": "templates/parallel-routes-with-default.tsx",
        "sha256": "513cac57ae53e33fd619cf15876320264fe93d366727426bef09549ceae2e541"
      }
    ],
    "dirSha256": "751d0e9f13f37b25b60eb7bd37981fed86ad120f2e150e053f240a521b9b9e85"
  },
  "security": {
    "scannedAt": null,
    "scannerVersion": null,
    "flags": []
  }
 }
--- a/references/next-16-migration-guide.md
+++ b/references/next-16-migration-guide.md
@@ -0,0 +1,647 @@
 # Next.js 16 Migration Guide
 **From**: Next.js 15.x
 **To**: Next.js 16.0.0
 **Last Updated**: 2025-10-24
 ---
 ## Table of Contents
 1. [Overview](#overview)
 2. [Breaking Changes](#breaking-changes)
 3. [New Features](#new-features)
 4. [Migration Steps](#migration-steps)
 5. [Automated Migration](#automated-migration)
 6. [Manual Migration](#manual-migration)
 7. [Troubleshooting](#troubleshooting)
 ---
 ## Overview
 Next.js 16 introduces significant changes:
 - **Breaking Changes**: 6 major breaking changes
 - **New Features**: Cache Components, updated caching APIs, React 19.2
 - **Performance**: Turbopack stable, 2–5× faster builds
 - **Migration Time**: ~1-2 hours for medium-sized apps
 **Recommendation**: Use automated codemod first, then manually fix remaining issues.
 ---
 ## Breaking Changes
 ### 1. Async Route Parameters ⚠️
 **What Changed**: `params`, `searchParams`, `cookies()`, `headers()`, `draftMode()` are now async.
 **Before** (Next.js 15):
 ```typescript
 export default function Page({ params, searchParams }) {
  const slug = params.slug
  const query = searchParams.q
 }
 ```
 **After** (Next.js 16):
 ```typescript
 export default async function Page({ params, searchParams }) {
  const { slug } = await params
  const { q: query } = await searchParams
 }
 ```
 **TypeScript Types**:
 ```typescript
 // Before
 type PageProps = {
  params: { slug: string }
  searchParams: { q: string }
 }
 // After
 type PageProps = {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ q: string }>
 }
 ```
 **Fix**:
 1. Add `async` to function
 2. Add `await` before params/searchParams
 3. Update TypeScript types to `Promise<>`
 ---
 ### 2. Middleware → Proxy ⚠️
 **What Changed**: `middleware.ts` is deprecated. Use `proxy.ts` instead.
 **Migration**:
 ```bash
 # 1. Rename file
 mv middleware.ts proxy.ts
 # 2. Rename function in file
 # middleware → proxy
 ```
 **Before** (middleware.ts):
 ```typescript
 export function middleware(request: NextRequest) {
  return NextResponse.next()
 }
 ```
 **After** (proxy.ts):
 ```typescript
 export function proxy(request: NextRequest) {
  return NextResponse.next()
 }
 ```
 **Note**: `middleware.ts` still works in Next.js 16 but is deprecated.
 ---
 ### 3. Parallel Routes Require `default.js` ⚠️
 **What Changed**: All parallel routes now REQUIRE explicit `default.js` files.
 **Before** (Next.js 15):
 ```
 app/
 ├── @modal/
 │   └── login/
 │       └── page.tsx
 ```
 **After** (Next.js 16):
 ```
 app/
 ├── @modal/
 │   ├── login/
 │   │   └── page.tsx
 │   └── default.tsx  ← REQUIRED
 ```
 **default.tsx**:
 ```typescript
 export default function ModalDefault() {
  return null
 }
 ```
 **Fix**: Add `default.tsx` to every `@folder` in parallel routes.
 ---
 ### 4. Removed Features ⚠️
 **Removed**:
 - AMP support
 - `next lint` command
 - `serverRuntimeConfig` and `publicRuntimeConfig`
 - `experimental.ppr` flag
 - Automatic `scroll-behavior: smooth`
 - Node.js 18 support
 **Migration**:
 **AMP**:
 ```typescript
 // Before
 export const config = { amp: true }
 // After
 // No direct replacement - use separate AMP pages or frameworks
 ```
 **Linting**:
 ```bash
 # Before
 npm run lint
 # After
 npx eslint .
 # or
 npx biome lint .
 ```
 **Runtime Config**:
 ```typescript
 // Before
 module.exports = {
  serverRuntimeConfig: { secret: 'abc' },
  publicRuntimeConfig: { apiUrl: 'https://api' },
 }
 // After
 // Use environment variables
 process.env.SECRET
 process.env.NEXT_PUBLIC_API_URL
 ```
 ---
 ### 5. Version Requirements ⚠️
 **Minimum Versions**:
 - Node.js: 20.9+ (Node 18 removed)
 - TypeScript: 5.1+
 - React: 19.2+
 - Browsers: Chrome 111+, Safari 16.4+, Firefox 109+
 **Upgrade Node.js**:
 ```bash
 # Check current version
 node --version
 # Upgrade (using nvm)
 nvm install 20
 nvm use 20
 nvm alias default 20
 # Verify
 node --version  # Should be 20.9+
 ```
 ---
 ### 6. Image Defaults Changed ⚠️
 **What Changed**: `next/image` default settings changed.
 | Setting | Next.js 15 | Next.js 16 |
 |---------|------------|------------|
 | TTL | 60s | 4 hours |
 | imageSizes | 8 sizes | 5 sizes |
 | qualities | 3 qualities | 1 quality (75) |
 **Impact**: Images cache longer, fewer sizes generated.
 **Revert** (if needed):
 ```typescript
 // next.config.ts
 const config = {
  images: {
    minimumCacheTTL: 60, // Revert to 60 seconds
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384], // Old sizes
  },
 }
 ```
 ---
 ## New Features
 ### 1. Cache Components ✨
 **Opt-in caching** with `"use cache"` directive.
 **Before** (Next.js 15 - implicit caching):
 ```typescript
 // All Server Components cached by default
 export async function MyComponent() {
  const data = await fetch('/api/data')
  return <div>{data.value}</div>
 }
 ```
 **After** (Next.js 16 - opt-in):
 ```typescript
 // NOT cached by default
 export async function MyComponent() {
  const data = await fetch('/api/data')
  return <div>{data.value}</div>
 }
 // Opt-in to caching
 'use cache'
 export async function CachedComponent() {
  const data = await fetch('/api/data')
  return <div>{data.value}</div>
 }
 ```
 **See**: `references/cache-components-guide.md`
 ---
 ### 2. Updated Caching APIs ✨
 **`revalidateTag()` now requires 2 arguments**:
 **Before**:
 ```typescript
 revalidateTag('posts')
 ```
 **After**:
 ```typescript
 revalidateTag('posts', 'max') // Second argument required
 ```
 **New APIs**:
 - `updateTag()` - Immediate refresh (read-your-writes)
 - `refresh()` - Refresh uncached data only
 ---
 ### 3. React 19.2 Integration ✨
 **New React features**:
 - View Transitions
 - `useEffectEvent()` (experimental)
 - React Compiler (stable)
 **See**: `references/react-19-integration.md`
 ---
 ### 4. Turbopack Stable ✨
 **Default bundler**: Turbopack is now stable and default.
 **Metrics**:
 - 2–5× faster production builds
 - Up to 10× faster Fast Refresh
 **Opt-out** (if incompatible):
 ```bash
 npm run build -- --webpack
 ```
 ---
 ## Migration Steps
 ### Step 1: Prerequisites
 1. **Backup your project**:
   ```bash
   git commit -am "Pre-migration checkpoint"
   ```
 2. **Check Node.js version**:
   ```bash
   node --version  # Should be 20.9+
   ```
 3. **Update dependencies**:
   ```bash
   npm install next@16 react@19.2 react-dom@19.2
   ```
 ---
 ### Step 2: Run Automated Codemod
 ```bash
 npx @next/codemod@canary upgrade latest
 ```
 **What it fixes**:
 - ✅ Async params (adds `await`)
 - ✅ Async searchParams
 - ✅ Async cookies()
 - ✅ Async headers()
 - ✅ Updates TypeScript types
 **What it does NOT fix**:
 - ❌ middleware.ts → proxy.ts (manual)
 - ❌ Parallel routes default.js (manual)
 - ❌ Removed features (manual)
 ---
 ### Step 3: Manual Fixes
 #### Fix 1: Migrate middleware.ts → proxy.ts
 ```bash
 # Rename file
 mv middleware.ts proxy.ts
 # Update function name
 # middleware → proxy
 ```
 #### Fix 2: Add default.js to Parallel Routes
 ```bash
 # For each @folder, create default.tsx
 touch app/@modal/default.tsx
 touch app/@feed/default.tsx
 ```
 ```typescript
 // app/@modal/default.tsx
 export default function ModalDefault() {
  return null
 }
 ```
 #### Fix 3: Replace Removed Features
 **AMP**: Remove AMP config or migrate to separate AMP implementation.
 **Linting**: Update scripts in `package.json`:
 ```json
 {
  "scripts": {
    "lint": "eslint ."
  }
 }
 ```
 **Runtime Config**: Use environment variables.
 ---
 ### Step 4: Update Caching
 **Migrate from implicit to explicit caching**:
 1. Find Server Components with expensive operations
 2. Add `"use cache"` directive
 3. Update `revalidateTag()` calls to include `cacheLife`
 **Example**:
 ```typescript
 // Before
 export async function ExpensiveComponent() {
  const data = await fetch('/api/data') // Cached implicitly
  return <div>{data.value}</div>
 }
 // After
 'use cache'
 export async function ExpensiveComponent() {
  const data = await fetch('/api/data') // Cached explicitly
  return <div>{data.value}</div>
 }
 ```
 ---
 ### Step 5: Test
 ```bash
 # Development
 npm run dev
 # Production build
 npm run build
 # Check for errors
 npm run type-check
 ```
 ---
 ### Step 6: Update CI/CD
 **Update Node.js version** in CI config:
 **.github/workflows/ci.yml**:
 ```yaml
 - uses: actions/setup-node@v4
  with:
    node-version: '20.9'  # Update from 18
 ```
 **Dockerfile**:
 ```dockerfile
 FROM node:20.9-alpine  # Update from node:18
 ```
 ---
 ## Automated Migration
 **Codemod** (recommended):
 ```bash
 npx @next/codemod@canary upgrade latest
 ```
 **Options**:
 - `--dry` - Preview changes without applying
 - `--force` - Skip confirmation prompts
 **What it migrates**:
 1. ✅ Async params
 2. ✅ Async searchParams
 3. ✅ Async cookies()
 4. ✅ Async headers()
 5. ✅ TypeScript types
 **Manual steps after codemod**:
 1. Rename middleware.ts → proxy.ts
 2. Add default.js to parallel routes
 3. Replace removed features
 4. Update caching patterns
 ---
 ## Manual Migration
 If codemod fails or you prefer manual migration:
 ### 1. Async Params
 **Find**:
 ```bash
 grep -r "params\." app/
 grep -r "searchParams\." app/
 ```
 **Replace**:
 ```typescript
 // Before
 const slug = params.slug
 // After
 const { slug } = await params
 ```
 ### 2. Async Cookies/Headers
 **Find**:
 ```bash
 grep -r "cookies()" app/
 grep -r "headers()" app/
 ```
 **Replace**:
 ```typescript
 // Before
 const cookieStore = cookies()
 // After
 const cookieStore = await cookies()
 ```
 ### 3. TypeScript Types
 **Find**: All `PageProps` types
 **Replace**:
 ```typescript
 // Before
 type PageProps = {
  params: { id: string }
  searchParams: { q: string }
 }
 // After
 type PageProps = {
  params: Promise<{ id: string }>
  searchParams: Promise<{ q: string }>
 }
 ```
 ---
 ## Troubleshooting
 ### Error: `params` is a Promise
 **Cause**: Not awaiting params in Next.js 16.
 **Fix**:
 ```typescript
 // ❌ Before
 const id = params.id
 // ✅ After
 const { id } = await params
 ```
 ---
 ### Error: Parallel route missing `default.js`
 **Cause**: Next.js 16 requires `default.js` for all parallel routes.
 **Fix**: Create `default.tsx`:
 ```typescript
 // app/@modal/default.tsx
 export default function ModalDefault() {
  return null
 }
 ```
 ---
 ### Error: `revalidateTag` requires 2 arguments
 **Cause**: `revalidateTag()` API changed in Next.js 16.
 **Fix**:
 ```typescript
 // ❌ Before
 revalidateTag('posts')
 // ✅ After
 revalidateTag('posts', 'max')
 ```
 ---
 ### Error: Turbopack build failure
 **Cause**: Turbopack is now default in Next.js 16.
 **Fix**: Opt-out if incompatible:
 ```bash
 npm run build -- --webpack
 ```
 ---
 ### Error: Node.js version too old
 **Cause**: Next.js 16 requires Node.js 20.9+.
 **Fix**: Upgrade Node.js:
 ```bash
 nvm install 20
 nvm use 20
 nvm alias default 20
 ```
 ---
 ## Migration Checklist
 - [ ] Backup project (git commit)
 - [ ] Check Node.js version (20.9+)
 - [ ] Update dependencies (`npm install next@16 react@19.2 react-dom@19.2`)
 - [ ] Run codemod (`npx @next/codemod@canary upgrade latest`)
 - [ ] Rename middleware.ts → proxy.ts
 - [ ] Add default.js to parallel routes
 - [ ] Remove AMP config (if used)
 - [ ] Replace runtime config with env vars
 - [ ] Update `revalidateTag()` calls (add `cacheLife`)
 - [ ] Add `"use cache"` where needed
 - [ ] Test dev server (`npm run dev`)
 - [ ] Test production build (`npm run build`)
 - [ ] Update CI/CD Node.js version
 - [ ] Deploy to staging
 - [ ] Deploy to production
 ---
 ## Resources
 - **Next.js 16 Blog**: https://nextjs.org/blog/next-16
 - **Codemod**: `npx @next/codemod@canary upgrade latest`
 - **Templates**: See `templates/` directory
 - **Common Errors**: See `references/top-errors.md`
 ---
 **Migration Support**: jeremy@jezweb.net
--- a/references/top-errors.md
+++ b/references/top-errors.md
@@ -0,0 +1,550 @@
 # Next.js 16 - Top 18 Errors & Solutions
 **Last Updated**: 2025-10-24
 **Prevention Rate**: 100% (all documented errors caught)
 This guide covers the 18 most common errors when using Next.js 16 and their solutions.
 ---
 ## Error #1: `params` is a Promise
 **Error Message**:
 ```
 Type 'Promise<{ id: string }>' is not assignable to type '{ id: string }'
 ```
 **Cause**: Next.js 16 changed `params` to async.
 **Solution**:
 ```typescript
 // ❌ Before (Next.js 15)
 export default function Page({ params }: { params: { id: string } }) {
  const id = params.id
 }
 // ✅ After (Next.js 16)
 export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
 }
 ```
 **TypeScript Fix**:
 ```typescript
 type Params<T = Record<string, string>> = Promise<T>
 ```
 ---
 ## Error #2: `searchParams` is a Promise
 **Error Message**:
 ```
 Property 'query' does not exist on type 'Promise<{ query: string }>'
 ```
 **Cause**: `searchParams` is now async in Next.js 16.
 **Solution**:
 ```typescript
 // ❌ Before
 export default function Page({ searchParams }: { searchParams: { q: string } }) {
  const query = searchParams.q
 }
 // ✅ After
 export default async function Page({ searchParams }: { searchParams: Promise<{ q: string }> }) {
  const { q: query } = await searchParams
 }
 ```
 ---
 ## Error #3: `cookies()` requires await
 **Error Message**:
 ```
 'cookies' implicitly has return type 'any'
 ```
 **Cause**: `cookies()` is async in Next.js 16.
 **Solution**:
 ```typescript
 // ❌ Before
 import { cookies } from 'next/headers'
 export function MyComponent() {
  const cookieStore = cookies()
  const token = cookieStore.get('token')
 }
 // ✅ After
 import { cookies } from 'next/headers'
 export async function MyComponent() {
  const cookieStore = await cookies()
  const token = cookieStore.get('token')
 }
 ```
 ---
 ## Error #4: `headers()` requires await
 **Error Message**:
 ```
 'headers' implicitly has return type 'any'
 ```
 **Cause**: `headers()` is async in Next.js 16.
 **Solution**:
 ```typescript
 // ❌ Before
 import { headers } from 'next/headers'
 export function MyComponent() {
  const headersList = headers()
 }
 // ✅ After
 import { headers } from 'next/headers'
 export async function MyComponent() {
  const headersList = await headers()
 }
 ```
 ---
 ## Error #5: Parallel route missing `default.js`
 **Error Message**:
 ```
 Error: Parallel route @modal/login was matched but no default.js was found
 ```
 **Cause**: Next.js 16 requires `default.js` for all parallel routes.
 **Solution**:
 ```typescript
 // Create app/@modal/default.tsx
 export default function ModalDefault() {
  return null
 }
 ```
 **Structure**:
 ```
 app/
 ├── @modal/
 │   ├── login/
 │   │   └── page.tsx
 │   └── default.tsx  ← REQUIRED
 ```
 ---
 ## Error #6: `revalidateTag()` requires 2 arguments
 **Error Message**:
 ```
 Expected 2 arguments, but got 1
 ```
 **Cause**: `revalidateTag()` API changed in Next.js 16.
 **Solution**:
 ```typescript
 // ❌ Before (Next.js 15)
 import { revalidateTag } from 'next/cache'
 revalidateTag('posts')
 // ✅ After (Next.js 16)
 import { revalidateTag } from 'next/cache'
 revalidateTag('posts', 'max') // Second argument required
 ```
 **Cache Life Profiles**:
 - `'max'` - Maximum staleness (recommended)
 - `'hours'` - Stale after hours
 - `'days'` - Stale after days
 - Custom: `{ stale: 3600, revalidate: 86400 }`
 ---
 ## Error #7: Cannot use React hooks in Server Component
 **Error Message**:
 ```
 You're importing a component that needs useState. It only works in a Client Component
 ```
 **Cause**: Using React hooks in Server Component.
 **Solution**: Add `'use client'` directive:
 ```typescript
 // ✅ 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>
 }
 ```
 ---
 ## Error #8: `middleware.ts` is deprecated
 **Warning Message**:
 ```
 Warning: middleware.ts is deprecated. Use proxy.ts instead.
 ```
 **Solution**: Migrate to `proxy.ts`:
 ```bash
 # 1. Rename file
 mv middleware.ts proxy.ts
 # 2. Rename function
 # middleware → proxy
 ```
 **Code**:
 ```typescript
 // ✅ proxy.ts
 export function proxy(request: NextRequest) {
  // Same logic
 }
 ```
 ---
 ## Error #9: Turbopack build failure
 **Error Message**:
 ```
 Error: Failed to compile with Turbopack
 ```
 **Cause**: Turbopack is now default in Next.js 16.
 **Solution 1** (opt-out):
 ```bash
 npm run build -- --webpack
 ```
 **Solution 2** (fix compatibility):
 Check for incompatible packages and update them.
 ---
 ## Error #10: Invalid `next/image` src
 **Error Message**:
 ```
 Invalid src prop (https://example.com/image.jpg) on `next/image`. Hostname "example.com" is not configured
 ```
 **Cause**: Remote images not configured.
 **Solution**: Add to `next.config.ts`:
 ```typescript
 const config = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        pathname: '/images/**',
      },
    ],
  },
 }
 ```
 ---
 ## Error #11: Cannot import Server Component into Client Component
 **Error Message**:
 ```
 You're importing a Server Component into a Client Component
 ```
 **Cause**: Direct import of Server Component in Client Component.
 **Solution**: Pass as children:
 ```typescript
 // ❌ Wrong
 'use client'
 import { ServerComponent } from './server-component'
 export function ClientComponent() {
  return <ServerComponent />
 }
 // ✅ Correct
 'use client'
 export function ClientComponent({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>
 }
 // Usage
 <ClientComponent>
  <ServerComponent /> {/* Pass as children */}
 </ClientComponent>
 ```
 ---
 ## Error #12: `generateStaticParams` not working
 **Error Message**:
 ```
 generateStaticParams is not generating static pages
 ```
 **Cause**: Missing `dynamic = 'force-static'`.
 **Solution**:
 ```typescript
 export const dynamic = 'force-static'
 export async function generateStaticParams() {
  const posts = await fetch('/api/posts').then(r => r.json())
  return posts.map((post: { id: string }) => ({ id: post.id }))
 }
 ```
 ---
 ## Error #13: `fetch()` not caching
 **Error Message**: Data not cached (performance issue).
 **Cause**: Next.js 16 uses opt-in caching.
 **Solution**: Add `"use cache"`:
 ```typescript
 'use cache'
 export async function getPosts() {
  const response = await fetch('/api/posts')
  return response.json()
 }
 ```
 ---
 ## Error #14: Route collision with Route Groups
 **Error Message**:
 ```
 Error: Conflicting routes: /about and /(marketing)/about
 ```
 **Cause**: Route groups creating same URL path.
 **Solution**: Ensure unique paths:
 ```
 app/
 ├── (marketing)/about/page.tsx     → /about
 └── (shop)/store-info/page.tsx     → /store-info (NOT /about)
 ```
 ---
 ## Error #15: Metadata not updating
 **Error Message**: SEO metadata not showing correctly.
 **Cause**: Using static metadata for dynamic pages.
 **Solution**: Use `generateMetadata()`:
 ```typescript
 export async function generateMetadata({ params }: { params: Promise<{ id: string }> }): Promise<Metadata> {
  const { id } = await params
  const post = await fetch(`/api/posts/${id}`).then(r => r.json())
  return {
    title: post.title,
    description: post.excerpt,
  }
 }
 ```
 ---
 ## Error #16: `next/font` font not loading
 **Error Message**: Custom fonts not applying.
 **Cause**: Font variable not applied to HTML element.
 **Solution**:
 ```typescript
 import { Inter } from 'next/font/google'
 const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
 export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html className={inter.variable}> {/* ✅ Apply variable */}
      <body>{children}</body>
    </html>
  )
 }
 ```
 ---
 ## Error #17: Environment variables not available in browser
 **Error Message**: `process.env.SECRET_KEY` is undefined in client.
 **Cause**: Server-only env vars not exposed to browser.
 **Solution**: Prefix with `NEXT_PUBLIC_`:
 ```bash
 # .env
 SECRET_KEY=abc123                  # Server-only
 NEXT_PUBLIC_API_URL=https://api    # Available in browser
 ```
 ```typescript
 // Server Component (both work)
 const secret = process.env.SECRET_KEY
 const apiUrl = process.env.NEXT_PUBLIC_API_URL
 // Client Component (only public vars)
 const apiUrl = process.env.NEXT_PUBLIC_API_URL
 ```
 ---
 ## Error #18: Server Action not found
 **Error Message**:
 ```
 Error: Could not find Server Action
 ```
 **Cause**: Missing `'use server'` directive.
 **Solution**:
 ```typescript
 // ❌ Before
 export async function createPost(formData: FormData) {
  await db.posts.create({ ... })
 }
 // ✅ After
 'use server'
 export async function createPost(formData: FormData) {
  await db.posts.create({ ... })
 }
 ```
 ---
 ## Quick Error Lookup
 | Error Type | Solution | Link |
 |------------|----------|------|
 | Async params | Add `await params` | [#1](#error-1-params-is-a-promise) |
 | Async searchParams | Add `await searchParams` | [#2](#error-2-searchparams-is-a-promise) |
 | Async cookies() | Add `await cookies()` | [#3](#error-3-cookies-requires-await) |
 | Async headers() | Add `await headers()` | [#4](#error-4-headers-requires-await) |
 | Missing default.js | Create `default.tsx` | [#5](#error-5-parallel-route-missing-defaultjs) |
 | revalidateTag 1 arg | Add `cacheLife` argument | [#6](#error-6-revalidatetag-requires-2-arguments) |
 | Hooks in Server Component | Add `'use client'` | [#7](#error-7-cannot-use-react-hooks-in-server-component) |
 | middleware.ts deprecated | Rename to `proxy.ts` | [#8](#error-8-middlewarets-is-deprecated) |
 | Turbopack failure | Use `--webpack` flag | [#9](#error-9-turbopack-build-failure) |
 | Invalid image src | Add `remotePatterns` | [#10](#error-10-invalid-nextimage-src) |
 | Import Server in Client | Pass as children | [#11](#error-11-cannot-import-server-component-into-client-component) |
 | generateStaticParams | Add `dynamic = 'force-static'` | [#12](#error-12-generatestaticparams-not-working) |
 | fetch not caching | Add `'use cache'` | [#13](#error-13-fetch-not-caching) |
 | Route collision | Use unique paths | [#14](#error-14-route-collision-with-route-groups) |
 | Metadata not updating | Use `generateMetadata()` | [#15](#error-15-metadata-not-updating) |
 | Font not loading | Apply font variable to `<html>` | [#16](#error-16-nextfont-font-not-loading) |
 | Env vars in browser | Prefix with `NEXT_PUBLIC_` | [#17](#error-17-environment-variables-not-available-in-browser) |
 | Server Action not found | Add `'use server'` | [#18](#error-18-server-action-not-found) |
 ---
 ## Prevention Checklist
 Before deploying, check:
 - [ ] All `params` are awaited
 - [ ] All `searchParams` are awaited
 - [ ] All `cookies()` calls are awaited
 - [ ] All `headers()` calls are awaited
 - [ ] All parallel routes have `default.js`
 - [ ] `revalidateTag()` has 2 arguments
 - [ ] Client Components have `'use client'`
 - [ ] `middleware.ts` migrated to `proxy.ts`
 - [ ] Remote images configured in `next.config.ts`
 - [ ] Server Components not imported directly in Client Components
 - [ ] Static pages have `dynamic = 'force-static'`
 - [ ] Cached components have `'use cache'`
 - [ ] No route collisions with Route Groups
 - [ ] Dynamic pages use `generateMetadata()`
 - [ ] Fonts applied to `<html>` or `<body>`
 - [ ] Public env vars prefixed with `NEXT_PUBLIC_`
 - [ ] Server Actions have `'use server'`
 - [ ] Node.js version is 20.9+
 ---
 ## Debugging Tips
 ### Enable TypeScript Strict Mode
 ```json
 // tsconfig.json
 {
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
 }
 ```
 ### Check Build Output
 ```bash
 npm run build
 ```
 Look for warnings and errors in build logs.
 ### Use Type Checking
 ```bash
 npx tsc --noEmit
 ```
 ### Check Runtime Logs
 ```bash
 npm run dev
 ```
 Watch console for errors and warnings.
 ---
 ## Resources
 - **Migration Guide**: `references/next-16-migration-guide.md`
 - **Templates**: `templates/` directory
 - **Next.js 16 Blog**: https://nextjs.org/blog/next-16
 - **Support**: jeremy@jezweb.net
--- a/scripts/check-versions.sh
+++ b/scripts/check-versions.sh
@@ -0,0 +1,207 @@
 #!/bin/bash
 # Next.js 16 - Version Checker
 # Verifies that all dependencies are compatible with Next.js 16
 set -e
 echo "🔍 Checking Next.js 16 compatibility..."
 echo ""
 # Colors
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 # Check if package.json exists
 if [ ! -f "package.json" ]; then
  echo -e "${RED}❌ package.json not found${NC}"
  echo "Run this script from your project root directory."
  exit 1
 fi
 # Check Node.js version
 echo "📦 Node.js Version:"
 NODE_VERSION=$(node --version | cut -d'v' -f2)
 NODE_MAJOR=$(echo $NODE_VERSION | cut -d'.' -f1)
 NODE_MINOR=$(echo $NODE_VERSION | cut -d'.' -f2)
 if [ "$NODE_MAJOR" -lt 20 ]; then
  echo -e "${RED}❌ Node.js $NODE_VERSION (requires 20.9+)${NC}"
  echo "   Upgrade: nvm install 20 && nvm use 20"
  exit 1
 elif [ "$NODE_MAJOR" -eq 20 ] && [ "$NODE_MINOR" -lt 9 ]; then
  echo -e "${RED}❌ Node.js $NODE_VERSION (requires 20.9+)${NC}"
  echo "   Upgrade: nvm install 20 && nvm use 20"
  exit 1
 else
  echo -e "${GREEN}✅ Node.js $NODE_VERSION${NC}"
 fi
 echo ""
 # Check Next.js version
 echo "🔧 Next.js Version:"
 if [ -f "node_modules/next/package.json" ]; then
  NEXT_VERSION=$(node -p "require('./node_modules/next/package.json').version")
  NEXT_MAJOR=$(echo $NEXT_VERSION | cut -d'.' -f1)
  if [ "$NEXT_MAJOR" -lt 16 ]; then
    echo -e "${RED}❌ Next.js $NEXT_VERSION (requires 16.0.0+)${NC}"
    echo "   Upgrade: npm install next@16"
    exit 1
  else
    echo -e "${GREEN}✅ Next.js $NEXT_VERSION${NC}"
  fi
 else
  echo -e "${YELLOW}⚠️  Next.js not installed (run npm install)${NC}"
 fi
 echo ""
 # Check React version
 echo "⚛️  React Version:"
 if [ -f "node_modules/react/package.json" ]; then
  REACT_VERSION=$(node -p "require('./node_modules/react/package.json').version")
  REACT_MAJOR=$(echo $REACT_VERSION | cut -d'.' -f1)
  REACT_MINOR=$(echo $REACT_VERSION | cut -d'.' -f2)
  if [ "$REACT_MAJOR" -lt 19 ]; then
    echo -e "${RED}❌ React $REACT_VERSION (requires 19.2+)${NC}"
    echo "   Upgrade: npm install react@19.2 react-dom@19.2"
    exit 1
  elif [ "$REACT_MAJOR" -eq 19 ] && [ "$REACT_MINOR" -lt 2 ]; then
    echo -e "${YELLOW}⚠️  React $REACT_VERSION (recommends 19.2+)${NC}"
    echo "   Upgrade: npm install react@19.2 react-dom@19.2"
  else
    echo -e "${GREEN}✅ React $REACT_VERSION${NC}"
  fi
 else
  echo -e "${YELLOW}⚠️  React not installed (run npm install)${NC}"
 fi
 echo ""
 # Check TypeScript version (if using TypeScript)
 if [ -f "tsconfig.json" ]; then
  echo "📘 TypeScript Version:"
  if [ -f "node_modules/typescript/package.json" ]; then
    TS_VERSION=$(node -p "require('./node_modules/typescript/package.json').version")
    TS_MAJOR=$(echo $TS_VERSION | cut -d'.' -f1)
    TS_MINOR=$(echo $TS_VERSION | cut -d'.' -f2)
    if [ "$TS_MAJOR" -lt 5 ]; then
      echo -e "${RED}❌ TypeScript $TS_VERSION (requires 5.1+)${NC}"
      echo "   Upgrade: npm install -D typescript@latest"
      exit 1
    elif [ "$TS_MAJOR" -eq 5 ] && [ "$TS_MINOR" -lt 1 ]; then
      echo -e "${RED}❌ TypeScript $TS_VERSION (requires 5.1+)${NC}"
      echo "   Upgrade: npm install -D typescript@latest"
      exit 1
    else
      echo -e "${GREEN}✅ TypeScript $TS_VERSION${NC}"
    fi
  else
    echo -e "${YELLOW}⚠️  TypeScript not installed (run npm install)${NC}"
  fi
  echo ""
 fi
 # Check for deprecated files
 echo "🔎 Checking for deprecated patterns..."
 DEPRECATED_FOUND=0
 if [ -f "middleware.ts" ]; then
  echo -e "${YELLOW}⚠️  middleware.ts found (deprecated in Next.js 16)${NC}"
  echo "   Migrate: Rename to proxy.ts and update function name"
  DEPRECATED_FOUND=1
 fi
 if [ -f "middleware.js" ]; then
  echo -e "${YELLOW}⚠️  middleware.js found (deprecated in Next.js 16)${NC}"
  echo "   Migrate: Rename to proxy.js and update function name"
  DEPRECATED_FOUND=1
 fi
 # Check for parallel routes missing default.js
 if [ -d "app" ]; then
  PARALLEL_ROUTES=$(find app -type d -name '@*' 2>/dev/null)
  if [ ! -z "$PARALLEL_ROUTES" ]; then
    for route in $PARALLEL_ROUTES; do
      if [ ! -f "$route/default.tsx" ] && [ ! -f "$route/default.jsx" ] && [ ! -f "$route/default.js" ]; then
        echo -e "${YELLOW}⚠️  $route missing default.tsx (required in Next.js 16)${NC}"
        echo "   Create: touch $route/default.tsx"
        DEPRECATED_FOUND=1
      fi
    done
  fi
 fi
 if [ $DEPRECATED_FOUND -eq 0 ]; then
  echo -e "${GREEN}✅ No deprecated patterns found${NC}"
 fi
 echo ""
 # Summary
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo "📊 Summary:"
 echo ""
 ALL_GOOD=1
 # Node.js check
 if [ "$NODE_MAJOR" -ge 20 ] && [ "$NODE_MINOR" -ge 9 ]; then
  echo -e "${GREEN}✅ Node.js compatible${NC}"
 else
  echo -e "${RED}❌ Node.js incompatible${NC}"
  ALL_GOOD=0
 fi
 # Next.js check
 if [ -f "node_modules/next/package.json" ]; then
  if [ "$NEXT_MAJOR" -ge 16 ]; then
    echo -e "${GREEN}✅ Next.js compatible${NC}"
  else
    echo -e "${RED}❌ Next.js incompatible${NC}"
    ALL_GOOD=0
  fi
 fi
 # React check
 if [ -f "node_modules/react/package.json" ]; then
  if [ "$REACT_MAJOR" -ge 19 ]; then
    echo -e "${GREEN}✅ React compatible${NC}"
  else
    echo -e "${RED}❌ React incompatible${NC}"
    ALL_GOOD=0
  fi
 fi
 # TypeScript check (if applicable)
 if [ -f "tsconfig.json" ] && [ -f "node_modules/typescript/package.json" ]; then
  if [ "$TS_MAJOR" -ge 5 ] && [ "$TS_MINOR" -ge 1 ]; then
    echo -e "${GREEN}✅ TypeScript compatible${NC}"
  else
    echo -e "${RED}❌ TypeScript incompatible${NC}"
    ALL_GOOD=0
  fi
 fi
 echo ""
 if [ $ALL_GOOD -eq 1 ] && [ $DEPRECATED_FOUND -eq 0 ]; then
  echo -e "${GREEN}🎉 All checks passed! Your project is ready for Next.js 16.${NC}"
  exit 0
 elif [ $ALL_GOOD -eq 1 ]; then
  echo -e "${YELLOW}⚠️  Dependencies compatible, but deprecated patterns found.${NC}"
  echo "Fix deprecation warnings before migrating to Next.js 16."
  exit 1
 else
  echo -e "${RED}❌ Compatibility issues found. Fix errors above before continuing.${NC}"
  exit 1
 fi
--- a/templates/app-router-async-params.tsx
+++ b/templates/app-router-async-params.tsx
@@ -0,0 +1,282 @@
 /**
 * Next.js 16 - Async Route Parameters
 *
 * BREAKING CHANGE: params, searchParams, cookies(), headers(), draftMode()
 * are now async and must be awaited in Next.js 16.
 *
 * This template shows the correct patterns for accessing route parameters,
 * search parameters, cookies, and headers in Next.js 16.
 */
 import { cookies, headers, draftMode } from 'next/headers'
 import { notFound } from 'next/navigation'
 // ============================================================================
 // Example 1: Page with Async Params
 // ============================================================================
 interface PageProps {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ q?: string; page?: string }>
 }
 export default async function BlogPostPage({ params, searchParams }: PageProps) {
  // ✅ Await params and searchParams in Next.js 16
  const { slug } = await params
  const { q, page } = await searchParams
  // Fetch post data
  const post = await fetch(`https://api.example.com/posts/${slug}`)
    .then(r => r.json())
    .catch(() => null)
  if (!post) {
    notFound()
  }
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
      {/* Show search query if present */}
      {q && <p>Search query: {q}</p>}
      {/* Show page number if present */}
      {page && <p>Page: {page}</p>}
    </article>
  )
 }
 // ============================================================================
 // Example 2: Layout with Async Params
 // ============================================================================
 interface LayoutProps {
  children: React.ReactNode
  params: Promise<{ category: string }>
 }
 export async function ProductLayout({ children, params }: LayoutProps) {
  // ✅ Await params in layouts too
  const { category } = await params
  return (
    <div>
      <nav>
        <h2>Category: {category}</h2>
      </nav>
      <main>{children}</main>
    </div>
  )
 }
 // ============================================================================
 // Example 3: Accessing Cookies (Async in Next.js 16)
 // ============================================================================
 export async function UserGreeting() {
  // ✅ Await cookies() in Next.js 16
  const cookieStore = await cookies()
  const userId = cookieStore.get('userId')?.value
  const theme = cookieStore.get('theme')?.value || 'light'
  if (!userId) {
    return <p>Welcome, Guest!</p>
  }
  const user = await fetch(`https://api.example.com/users/${userId}`)
    .then(r => r.json())
  return (
    <div data-theme={theme}>
      <p>Welcome back, {user.name}!</p>
    </div>
  )
 }
 // ============================================================================
 // Example 4: Accessing Headers (Async in Next.js 16)
 // ============================================================================
 export async function RequestInfo() {
  // ✅ Await headers() in Next.js 16
  const headersList = await headers()
  const userAgent = headersList.get('user-agent') || 'Unknown'
  const referer = headersList.get('referer') || 'Direct'
  const ip = headersList.get('x-forwarded-for') || 'Unknown'
  return (
    <div>
      <p>User Agent: {userAgent}</p>
      <p>Referrer: {referer}</p>
      <p>IP: {ip}</p>
    </div>
  )
 }
 // ============================================================================
 // Example 5: Draft Mode (Async in Next.js 16)
 // ============================================================================
 export async function DraftBanner() {
  // ✅ Await draftMode() in Next.js 16
  const { isEnabled } = await draftMode()
  if (!isEnabled) {
    return null
  }
  return (
    <div style={{ background: 'yellow', padding: '1rem' }}>
      <p>🚧 Draft Mode Enabled</p>
      <a href="/api/disable-draft">Exit Draft Mode</a>
    </div>
  )
 }
 // ============================================================================
 // Example 6: Generate Metadata with Async Params
 // ============================================================================
 import type { Metadata } from 'next'
 export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  // ✅ Await params in generateMetadata
  const { slug } = await params
  const post = await fetch(`https://api.example.com/posts/${slug}`)
    .then(r => r.json())
  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [post.coverImage],
    },
  }
 }
 // ============================================================================
 // Example 7: Generate Static Params (Async)
 // ============================================================================
 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,
  }))
 }
 // ============================================================================
 // Example 8: Route Handler with Async Params
 // ============================================================================
 // File: app/api/posts/[id]/route.ts
 import { NextResponse } from 'next/server'
 export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
 ) {
  // ✅ Await params in route handlers
  const { id } = await params
  const post = await fetch(`https://api.example.com/posts/${id}`)
    .then(r => r.json())
  return NextResponse.json(post)
 }
 export async function DELETE(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
 ) {
  // ✅ Await params in route handlers
  const { id } = await params
  await fetch(`https://api.example.com/posts/${id}`, {
    method: 'DELETE',
  })
  return NextResponse.json({ message: 'Post deleted' })
 }
 // ============================================================================
 // Migration Guide: Next.js 15 → Next.js 16
 // ============================================================================
 // ❌ BEFORE (Next.js 15):
 /*
 export default function Page({ params, searchParams }) {
  const slug = params.slug // ❌ Sync access
  const query = searchParams.q // ❌ Sync access
 }
 export function MyComponent() {
  const cookieStore = cookies() // ❌ Sync access
  const headersList = headers() // ❌ Sync access
 }
 */
 // ✅ AFTER (Next.js 16):
 /*
 export default async function Page({ params, searchParams }) {
  const { slug } = await params // ✅ Async access
  const { q: query } = await searchParams // ✅ Async access
 }
 export async function MyComponent() {
  const cookieStore = await cookies() // ✅ Async access
  const headersList = await headers() // ✅ Async access
 }
 */
 // ============================================================================
 // TypeScript Types
 // ============================================================================
 // Correct types for Next.js 16:
 type Params<T = Record<string, string>> = Promise<T>
 type SearchParams = Promise<{ [key: string]: string | string[] | undefined }>
 // Usage:
 type ProductPageProps = {
  params: Params<{ id: string }>
  searchParams: SearchParams
 }
 // ============================================================================
 // Codemod (Automatic Migration)
 // ============================================================================
 // Run this command to automatically migrate your code:
 // npx @next/codemod@canary upgrade latest
 /**
 * Summary:
 *
 * 1. ALL route parameters are now async:
 *    - params → await params
 *    - searchParams → await searchParams
 *
 * 2. ALL next/headers functions are now async:
 *    - cookies() → await cookies()
 *    - headers() → await headers()
 *    - draftMode() → await draftMode()
 *
 * 3. Components using these must be async:
 *    - export default async function Page({ params }) { ... }
 *    - export async function Layout({ params }) { ... }
 *    - export async function generateMetadata({ params }) { ... }
 *
 * 4. Route handlers must await params:
 *    - export async function GET(request, { params }) {
 *        const { id } = await params
 *      }
 */
--- a/templates/cache-component-use-cache.tsx
+++ b/templates/cache-component-use-cache.tsx
@@ -0,0 +1,343 @@
 /**
 * Next.js 16 - Cache Components with "use cache" Directive
 *
 * NEW in Next.js 16: Explicit opt-in caching with "use cache" directive.
 * Replaces implicit caching from Next.js 15.
 *
 * This template shows component-level, function-level, and page-level caching.
 */
 // ============================================================================
 // Example 1: Component-Level Caching
 // ============================================================================
 'use cache'
 // This entire component will be cached
 export async function CachedProductList() {
  const products = await fetch('https://api.example.com/products')
    .then(r => r.json())
  return (
    <div>
      <h2>Products</h2>
      <ul>
        {products.map((product: { id: string; name: string; price: number }) => (
          <li key={product.id}>
            {product.name} - ${product.price}
          </li>
        ))}
      </ul>
    </div>
  )
 }
 // ============================================================================
 // Example 2: Function-Level Caching
 // ============================================================================
 // File: lib/data.ts
 'use cache'
 export async function getExpensiveData(id: string) {
  console.log('Fetching expensive data...') // Only logs on cache miss
  // Simulate expensive operation
  await new Promise(resolve => setTimeout(resolve, 1000))
  const data = await fetch(`https://api.example.com/items/${id}`)
    .then(r => r.json())
  return data
 }
 // Usage in component (not cached itself):
 import { getExpensiveData } from '@/lib/data'
 export async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const product = await getExpensiveData(id) // Cached by function
  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
    </div>
  )
 }
 // ============================================================================
 // Example 3: Page-Level Caching
 // ============================================================================
 // File: 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 dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  )
 }
 // ============================================================================
 // Example 4: Partial Prerendering (PPR) - Mix Static & Dynamic
 // ============================================================================
 // File: app/dashboard/page.tsx
 // Static component (cached)
 'use cache'
 async function StaticHeader() {
  return (
    <header>
      <h1>My Dashboard</h1>
      <nav>
        <a href="/dashboard">Overview</a>
        <a href="/dashboard/settings">Settings</a>
      </nav>
    </header>
  )
 }
 // Dynamic component (NOT cached) - separate file without "use cache"
 // File: components/dynamic-user-info.tsx
 import { cookies } from 'next/headers'
 export async function DynamicUserInfo() {
  const cookieStore = await cookies()
  const userId = cookieStore.get('userId')?.value
  if (!userId) {
    return <div>Please log in</div>
  }
  const user = await fetch(`https://api.example.com/users/${userId}`)
    .then(r => r.json())
  return (
    <div>
      <p>Welcome, {user.name}</p>
      <p>Balance: ${user.balance}</p>
    </div>
  )
 }
 // Page combines static + dynamic (Partial Prerendering)
 import { DynamicUserInfo } from '@/components/dynamic-user-info'
 export default function DashboardPage() {
  return (
    <div>
      <StaticHeader /> {/* Cached (static) */}
      <DynamicUserInfo /> {/* Not cached (dynamic) */}
    </div>
  )
 }
 // ============================================================================
 // Example 5: Selective Caching with Multiple Functions
 // ============================================================================
 // Cache expensive operations, skip cheap ones
 // Cached function
 'use cache'
 export async function getPopularPosts() {
  const posts = await fetch('https://api.example.com/posts/popular')
    .then(r => r.json())
  return posts
 }
 // NOT cached (changes frequently)
 export async function getRealtimeMetrics() {
  const metrics = await fetch('https://api.example.com/metrics/realtime')
    .then(r => r.json())
  return metrics
 }
 // Component uses both
 export async function Dashboard() {
  const popularPosts = await getPopularPosts() // Cached
  const metrics = await getRealtimeMetrics() // NOT cached
  return (
    <div>
      <div>
        <h2>Popular Posts</h2>
        <ul>
          {popularPosts.map((post: { id: string; title: string }) => (
            <li key={post.id}>{post.title}</li>
          ))}
        </ul>
      </div>
      <div>
        <h2>Realtime Metrics</h2>
        <p>Active users: {metrics.activeUsers}</p>
        <p>Requests/min: {metrics.requestsPerMinute}</p>
      </div>
    </div>
  )
 }
 // ============================================================================
 // Example 6: Cache with Revalidation (using tags)
 // ============================================================================
 // File: app/actions.ts
 '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('https://api.example.com/posts', {
    method: 'POST',
    body: JSON.stringify({ title, content }),
  })
  // Revalidate cached posts
  revalidateTag('posts', 'max')
 }
 // File: lib/posts.ts
 'use cache'
 export async function getPosts() {
  const response = await fetch('https://api.example.com/posts', {
    next: { tags: ['posts'] }, // Tag for revalidation
  })
  return response.json()
 }
 // ============================================================================
 // Example 7: Conditional Caching (Cache Based on User Role)
 // ============================================================================
 import { cookies } from 'next/headers'
 export async function getContent() {
  const cookieStore = await cookies()
  const userRole = cookieStore.get('role')?.value
  if (userRole === 'admin') {
    // Don't cache admin content (changes frequently)
    return fetch('https://api.example.com/admin/content').then(r => r.json())
  }
  // Cache public content
  return getCachedPublicContent()
 }
 'use cache'
 async function getCachedPublicContent() {
  return fetch('https://api.example.com/public/content').then(r => r.json())
 }
 // ============================================================================
 // Example 8: Inline "use cache" (Granular Control)
 // ============================================================================
 export async function MixedCachingComponent() {
  // This function call is cached
  const cachedData = await (async function() {
    'use cache'
    return fetch('https://api.example.com/slow-data').then(r => r.json())
  })()
  // This function call is NOT cached
  const freshData = await fetch('https://api.example.com/fresh-data').then(r => r.json())
  return (
    <div>
      <div>Cached: {cachedData.value}</div>
      <div>Fresh: {freshData.value}</div>
    </div>
  )
 }
 // ============================================================================
 // Migration Guide: Next.js 15 → Next.js 16
 // ============================================================================
 // ❌ BEFORE (Next.js 15 - Implicit Caching):
 /*
 // All Server Components were cached by default
 export async function MyComponent() {
  const data = await fetch('https://api.example.com/data')
  return <div>{data.value}</div>
 }
 // To opt-out of caching:
 export const revalidate = 0 // or export const dynamic = 'force-dynamic'
 */
 // ✅ AFTER (Next.js 16 - Explicit Opt-In Caching):
 /*
 // Components are NOT cached by default
 export async function MyComponent() {
  const data = await fetch('https://api.example.com/data')
  return <div>{data.value}</div>
 }
 // To opt-IN to caching, add "use cache"
 'use cache'
 export async function MyCachedComponent() {
  const data = await fetch('https://api.example.com/data')
  return <div>{data.value}</div>
 }
 */
 // ============================================================================
 // Cache Behavior Summary
 // ============================================================================
 /**
 * "use cache" can be added to:
 * 1. ✅ Components (entire component cached)
 * 2. ✅ Functions (function output cached)
 * 3. ✅ Pages (entire page cached)
 * 4. ✅ Layouts (layout cached)
 * 5. ✅ Inline async functions (granular caching)
 *
 * Default behavior (without "use cache"):
 * - Server Components: NOT cached (change from Next.js 15)
 * - fetch() calls: Cached by default (unchanged)
 *
 * Revalidation:
 * - Use revalidateTag() to invalidate cache by tag
 * - Use updateTag() for immediate read-your-writes
 * - Use refresh() for uncached data only
 *
 * When to use "use cache":
 * ✅ Expensive computations (database queries, API calls)
 * ✅ Stable data (product catalogs, blog posts)
 * ✅ Partial Prerendering (static header + dynamic user info)
 *
 * When NOT to use "use cache":
 * ❌ Real-time data (metrics, notifications)
 * ❌ User-specific data (unless using cookies/headers for cache keys)
 * ❌ Frequently changing data (stock prices, live scores)
 */
--- a/templates/package.json
+++ b/templates/package.json
@@ -0,0 +1,32 @@
 {
  "name": "nextjs-16-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "type-check": "tsc --noEmit"
  },
  "dependencies": {
    "next": "^16.0.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "typescript": "^5.7.0"
  },
  "optionalDependencies": {
    "zod": "^3.24.0",
    "@tailwindcss/vite": "^4.1.0",
    "tailwindcss": "^4.1.0"
  },
  "engines": {
    "node": ">=20.9.0",
    "npm": ">=10.0.0"
  }
 }
--- a/templates/parallel-routes-with-default.tsx
+++ b/templates/parallel-routes-with-default.tsx
@@ -0,0 +1,437 @@
 /**
 * Next.js 16 - Parallel Routes with Required default.js
 *
 * BREAKING CHANGE: Parallel routes now REQUIRE explicit default.js files.
 * Without them, routes will fail during soft navigation.
 *
 * Directory structure:
 * 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
 */
 // ============================================================================
 // Example 1: Modal + Main Content (Common Pattern)
 // ============================================================================
 // File: app/layout.tsx
 export default function RootLayout({
  children,
  modal,
 }: {
  children: React.ReactNode
  modal: React.ReactNode
 }) {
  return (
    <html>
      <body>
        {modal}
        <main>{children}</main>
      </body>
    </html>
  )
 }
 // File: app/@modal/login/page.tsx
 export default function LoginModal() {
  return (
    <div className="modal-overlay">
      <div className="modal">
        <h2>Login</h2>
        <form>
          <input type="email" placeholder="Email" />
          <input type="password" placeholder="Password" />
          <button type="submit">Login</button>
        </form>
      </div>
    </div>
  )
 }
 // File: app/@modal/default.tsx (REQUIRED)
 export default function ModalDefault() {
  return null // No modal shown by default
 }
 // File: app/page.tsx
 export default function HomePage() {
  return (
    <div>
      <h1>Home Page</h1>
      <a href="/login">Open Login Modal</a>
    </div>
  )
 }
 // ============================================================================
 // Example 2: Dashboard with Multiple Panels
 // ============================================================================
 // File: app/dashboard/layout.tsx
 export default function DashboardLayout({
  children,
  analytics,
  notifications,
  activity,
 }: {
  children: React.ReactNode
  analytics: React.ReactNode
  notifications: React.ReactNode
  activity: React.ReactNode
 }) {
  return (
    <div className="dashboard-layout">
      <aside className="sidebar">
        {notifications}
      </aside>
      <main className="main-content">
        {children}
        {analytics}
      </main>
      <aside className="activity-sidebar">
        {activity}
      </aside>
    </div>
  )
 }
 // File: app/dashboard/@analytics/overview/page.tsx
 export default async function AnalyticsOverview() {
  const stats = await fetch('https://api.example.com/stats').then(r => r.json())
  return (
    <div className="analytics-panel">
      <h2>Analytics</h2>
      <div>
        <p>Page Views: {stats.pageViews}</p>
        <p>Unique Visitors: {stats.uniqueVisitors}</p>
      </div>
    </div>
  )
 }
 // File: app/dashboard/@analytics/default.tsx (REQUIRED)
 export default function AnalyticsDefault() {
  return (
    <div className="analytics-panel">
      <h2>Analytics</h2>
      <p>No analytics data available</p>
    </div>
  )
 }
 // File: app/dashboard/@notifications/default.tsx (REQUIRED)
 export default function NotificationsDefault() {
  return (
    <div className="notifications-panel">
      <h3>Notifications</h3>
      <p>No new notifications</p>
    </div>
  )
 }
 // File: app/dashboard/@activity/default.tsx (REQUIRED)
 export default function ActivityDefault() {
  return (
    <div className="activity-panel">
      <h3>Recent Activity</h3>
      <p>No recent activity</p>
    </div>
  )
 }
 // ============================================================================
 // Example 3: E-commerce with Product + Reviews
 // ============================================================================
 // File: app/products/[id]/layout.tsx
 export default function ProductLayout({
  children,
  reviews,
  recommendations,
 }: {
  children: React.ReactNode
  reviews: React.ReactNode
  recommendations: React.ReactNode
 }) {
  return (
    <div className="product-layout">
      <div className="product-main">
        {children}
      </div>
      <div className="product-sidebar">
        {reviews}
        {recommendations}
      </div>
    </div>
  )
 }
 // File: app/products/[id]/@reviews/page.tsx
 export default async function ProductReviews({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const reviews = await fetch(`https://api.example.com/products/${id}/reviews`)
    .then(r => r.json())
  return (
    <div className="reviews">
      <h3>Reviews</h3>
      <ul>
        {reviews.map((review: { id: string; rating: number; comment: string }) => (
          <li key={review.id}>
            <p>⭐ {review.rating}/5</p>
            <p>{review.comment}</p>
          </li>
        ))}
      </ul>
    </div>
  )
 }
 // File: app/products/[id]/@reviews/default.tsx (REQUIRED)
 export default function ReviewsDefault() {
  return (
    <div className="reviews">
      <h3>Reviews</h3>
      <p>No reviews yet</p>
    </div>
  )
 }
 // File: app/products/[id]/@recommendations/default.tsx (REQUIRED)
 export default function RecommendationsDefault() {
  return (
    <div className="recommendations">
      <h3>Recommendations</h3>
      <p>Loading recommendations...</p>
    </div>
  )
 }
 // ============================================================================
 // Example 4: Auth-Gated Content
 // ============================================================================
 import { cookies } from 'next/headers'
 import { redirect } from 'next/navigation'
 // File: app/@auth/default.tsx (REQUIRED)
 export default async function AuthDefault() {
  const cookieStore = await cookies()
  const isAuthenticated = cookieStore.get('auth')?.value
  if (!isAuthenticated) {
    redirect('/login')
  }
  return null
 }
 // File: app/@auth/profile/page.tsx
 export default async function ProfilePage() {
  const cookieStore = await cookies()
  const userId = cookieStore.get('userId')?.value
  const user = await fetch(`https://api.example.com/users/${userId}`)
    .then(r => r.json())
  return (
    <div>
      <h2>Profile</h2>
      <p>Name: {user.name}</p>
      <p>Email: {user.email}</p>
    </div>
  )
 }
 // ============================================================================
 // Example 5: Conditional Rendering Based on Slot
 // ============================================================================
 // File: app/layout.tsx
 export default function Layout({
  children,
  banner,
 }: {
  children: React.ReactNode
  banner: React.ReactNode
 }) {
  // Only show banner on specific pages
  const showBanner = true // Determine based on route
  return (
    <html>
      <body>
        {showBanner && banner}
        <main>{children}</main>
      </body>
    </html>
  )
 }
 // File: app/@banner/sale/page.tsx
 export default function SaleBanner() {
  return (
    <div className="banner sale-banner">
      🎉 50% OFF SALE! Use code SALE50
    </div>
  )
 }
 // File: app/@banner/default.tsx (REQUIRED)
 export default function BannerDefault() {
  return null // No banner by default
 }
 // ============================================================================
 // Example 6: Loading States with Parallel Routes
 // ============================================================================
 // File: app/dashboard/@analytics/loading.tsx
 export default function AnalyticsLoading() {
  return (
    <div className="analytics-panel">
      <h2>Analytics</h2>
      <p>Loading analytics...</p>
      <div className="skeleton-loader" />
    </div>
  )
 }
 // File: app/dashboard/@notifications/loading.tsx
 export default function NotificationsLoading() {
  return (
    <div className="notifications-panel">
      <h3>Notifications</h3>
      <div className="skeleton-loader" />
    </div>
  )
 }
 // ============================================================================
 // Example 7: Error Boundaries with Parallel Routes
 // ============================================================================
 // File: app/dashboard/@analytics/error.tsx
 'use client'
 export default function AnalyticsError({
  error,
  reset,
 }: {
  error: Error
  reset: () => void
 }) {
  return (
    <div className="analytics-panel error">
      <h2>Analytics</h2>
      <p>Failed to load analytics</p>
      <button onClick={reset}>Try Again</button>
    </div>
  )
 }
 // ============================================================================
 // Migration Guide: Next.js 15 → Next.js 16
 // ============================================================================
 /**
 * BREAKING CHANGE: default.js is now REQUIRED for all parallel routes
 *
 * ❌ BEFORE (Next.js 15):
 * app/
 * ├── @modal/
 * │   └── login/
 * │       └── page.tsx
 * └── layout.tsx
 *
 * This worked in Next.js 15. If no matching route, Next.js rendered nothing.
 *
 * ✅ AFTER (Next.js 16):
 * app/
 * ├── @modal/
 * │   ├── login/
 * │   │   └── page.tsx
 * │   └── default.tsx    ← REQUIRED! Will error without this
 * └── layout.tsx
 *
 * Why the change?
 * Next.js 16 changed how parallel routes handle soft navigation. Without
 * default.js, unmatched slots will error during client-side navigation.
 *
 * What should default.tsx return?
 * - return null (most common - no UI shown)
 * - return <Skeleton /> (loading placeholder)
 * - redirect() to another route
 * - return fallback UI
 */
 // ============================================================================
 // Common Patterns for default.tsx
 // ============================================================================
 // Pattern 1: Null (no UI)
 export function DefaultNull() {
  return null
 }
 // Pattern 2: Loading skeleton
 export function DefaultSkeleton() {
  return (
    <div className="skeleton">
      <div className="skeleton-line" />
      <div className="skeleton-line" />
      <div className="skeleton-line" />
    </div>
  )
 }
 // Pattern 3: Fallback message
 export function DefaultFallback() {
  return (
    <div>
      <p>Content not available</p>
    </div>
  )
 }
 // Pattern 4: Redirect
 import { redirect } from 'next/navigation'
 export function DefaultRedirect() {
  redirect('/dashboard')
 }
 /**
 * Summary:
 *
 * Parallel Routes in Next.js 16:
 * 1. ✅ Use @folder convention for parallel slots
 * 2. ✅ MUST include default.tsx for each @folder
 * 3. ✅ default.tsx handles unmatched routes during navigation
 * 4. ✅ Can have loading.tsx for loading states
 * 5. ✅ Can have error.tsx for error boundaries
 *
 * Common use cases:
 * - Modals + main content
 * - Dashboard panels
 * - Product + reviews/recommendations
 * - Conditional banners
 * - Auth-gated content
 *
 * Best practices:
 * - Keep default.tsx simple (usually return null)
 * - Use loading.tsx for better UX
 * - Use error.tsx for error handling
 * - Test soft navigation (client-side routing)
 */
--- a/templates/proxy-migration.ts
+++ b/templates/proxy-migration.ts
@@ -0,0 +1,274 @@
 /**
 * Next.js 16 - Proxy Migration (middleware.ts → proxy.ts)
 *
 * BREAKING CHANGE: middleware.ts is deprecated in Next.js 16.
 * Use proxy.ts instead.
 *
 * Migration: Rename file and function, keep same logic.
 */
 import { NextResponse } from 'next/server'
 import type { NextRequest } from 'next/server'
 // ============================================================================
 // Example 1: Basic Proxy (Auth Check)
 // ============================================================================
 export function proxy(request: NextRequest) {
  const token = request.cookies.get('token')
  // Redirect to login if no token
  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  return NextResponse.next()
 }
 export const config = {
  matcher: '/dashboard/:path*',
 }
 // ============================================================================
 // Example 2: Advanced Proxy (Multiple Checks)
 // ============================================================================
 export function advancedProxy(request: NextRequest) {
  const { pathname } = request.nextUrl
  // 1. Auth check
  const token = request.cookies.get('token')
  if (pathname.startsWith('/dashboard') && !token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  // 2. Role-based access
  const userRole = request.cookies.get('role')?.value
  if (pathname.startsWith('/admin') && userRole !== 'admin') {
    return NextResponse.redirect(new URL('/unauthorized', request.url))
  }
  // 3. Add custom headers
  const response = NextResponse.next()
  response.headers.set('x-custom-header', 'value')
  response.headers.set('x-pathname', pathname)
  return response
 }
 export const advancedConfig = {
  matcher: ['/dashboard/:path*', '/admin/:path*'],
 }
 // ============================================================================
 // Example 3: Request Rewriting
 // ============================================================================
 export function rewriteProxy(request: NextRequest) {
  // Rewrite /blog/* to /posts/*
  if (request.nextUrl.pathname.startsWith('/blog')) {
    const url = request.nextUrl.clone()
    url.pathname = url.pathname.replace('/blog', '/posts')
    return NextResponse.rewrite(url)
  }
  return NextResponse.next()
 }
 export const rewriteConfig = {
  matcher: '/blog/:path*',
 }
 // ============================================================================
 // Example 4: Geolocation-Based Routing
 // ============================================================================
 export function geoProxy(request: NextRequest) {
  const country = request.geo?.country || 'US'
  const url = request.nextUrl.clone()
  // Redirect to country-specific page
  if (url.pathname === '/') {
    url.pathname = `/${country.toLowerCase()}`
    return NextResponse.rewrite(url)
  }
  return NextResponse.next()
 }
 // ============================================================================
 // Example 5: A/B Testing
 // ============================================================================
 export function abTestProxy(request: NextRequest) {
  const bucket = request.cookies.get('bucket')?.value
  if (!bucket) {
    // Assign to A or B randomly
    const newBucket = Math.random() < 0.5 ? 'a' : 'b'
    const response = NextResponse.next()
    response.cookies.set('bucket', newBucket, {
      maxAge: 60 * 60 * 24 * 30, // 30 days
    })
    // Rewrite to variant page
    if (newBucket === 'b') {
      const url = request.nextUrl.clone()
      url.pathname = `/variant-b${url.pathname}`
      return NextResponse.rewrite(url)
    }
    return response
  }
  // Existing user
  if (bucket === 'b') {
    const url = request.nextUrl.clone()
    url.pathname = `/variant-b${url.pathname}`
    return NextResponse.rewrite(url)
  }
  return NextResponse.next()
 }
 export const abTestConfig = {
  matcher: '/',
 }
 // ============================================================================
 // Example 6: Rate Limiting
 // ============================================================================
 const rateLimitMap = new Map<string, { count: number; resetAt: number }>()
 export function rateLimitProxy(request: NextRequest) {
  const ip = request.headers.get('x-forwarded-for') || 'unknown'
  const now = Date.now()
  // Check rate limit (100 requests per minute)
  const rateLimit = rateLimitMap.get(ip)
  if (rateLimit) {
    if (now < rateLimit.resetAt) {
      if (rateLimit.count >= 100) {
        return new NextResponse('Too Many Requests', {
          status: 429,
          headers: {
            'Retry-After': String(Math.ceil((rateLimit.resetAt - now) / 1000)),
          },
        })
      }
      rateLimit.count++
    } else {
      rateLimitMap.set(ip, { count: 1, resetAt: now + 60000 }) // 1 minute
    }
  } else {
    rateLimitMap.set(ip, { count: 1, resetAt: now + 60000 })
  }
  return NextResponse.next()
 }
 export const rateLimitConfig = {
  matcher: '/api/:path*',
 }
 // ============================================================================
 // Example 7: Response Modification
 // ============================================================================
 export function modifyResponseProxy(request: NextRequest) {
  const response = NextResponse.next()
  // Add security headers
  response.headers.set('X-Frame-Options', 'DENY')
  response.headers.set('X-Content-Type-Options', 'nosniff')
  response.headers.set('Referrer-Policy', 'origin-when-cross-origin')
  response.headers.set(
    'Permissions-Policy',
    'camera=(), microphone=(), geolocation=()'
  )
  return response
 }
 // ============================================================================
 // Migration Guide: middleware.ts → proxy.ts
 // ============================================================================
 /**
 * ❌ BEFORE (Next.js 15):
 *
 * // File: middleware.ts
 * import { NextResponse } from 'next/server'
 * import type { NextRequest } from 'next/server'
 *
 * export function middleware(request: NextRequest) {
 *   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 (Next.js 16):
 *
 * // File: proxy.ts
 * import { NextResponse } from 'next/server'
 * import type { NextRequest } from 'next/server'
 *
 * export function proxy(request: NextRequest) {
 *   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*',
 * }
 */
 /**
 * Migration Steps:
 * 1. Rename file: middleware.ts → proxy.ts
 * 2. Rename function: middleware → proxy
 * 3. Keep config object the same
 * 4. Logic remains identical
 *
 * Why the change?
 * - proxy.ts runs on Node.js runtime (full Node.js APIs)
 * - middleware.ts ran on Edge runtime (limited APIs)
 * - proxy.ts makes the network boundary explicit
 *
 * Note: middleware.ts still works in Next.js 16 but is deprecated.
 * Migrate to proxy.ts for future compatibility.
 */
 /**
 * Summary:
 *
 * Proxy patterns:
 * 1. ✅ Auth checks and redirects
 * 2. ✅ Role-based access control
 * 3. ✅ Custom headers
 * 4. ✅ Request rewriting (URL rewrites)
 * 5. ✅ Geolocation-based routing
 * 6. ✅ A/B testing
 * 7. ✅ Rate limiting
 * 8. ✅ Response modification (security headers)
 *
 * Best practices:
 * - Keep proxy logic lightweight (runs on every request)
 * - Use matcher to limit scope
 * - Avoid database queries (use cookies/headers instead)
 * - Cache rate limit data in memory (or Redis for production)
 * - Return NextResponse.next() if no action needed
 */
--- a/templates/route-handler-api.ts
+++ b/templates/route-handler-api.ts
@@ -0,0 +1,393 @@
 /**
 * Next.js 16 - Route Handlers (API Endpoints)
 *
 * Route Handlers replace API Routes from Pages Router.
 * File: app/api/[...]/route.ts
 */
 import { NextResponse } from 'next/server'
 import { cookies, headers } from 'next/headers'
 // ============================================================================
 // Example 1: Basic CRUD API
 // ============================================================================
 // GET /api/posts
 export async function GET() {
  const posts = await fetch('https://api.example.com/posts').then(r => r.json())
  return NextResponse.json(posts)
 }
 // POST /api/posts
 export async function POST(request: Request) {
  const body = await request.json()
  const post = await fetch('https://api.example.com/posts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  }).then(r => r.json())
  return NextResponse.json(post, { status: 201 })
 }
 // ============================================================================
 // Example 2: Dynamic Routes
 // ============================================================================
 // File: app/api/posts/[id]/route.ts
 export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
 ) {
  const { id } = await params // ✅ Await params in Next.js 16
  const post = await fetch(`https://api.example.com/posts/${id}`)
    .then(r => r.json())
    .catch(() => null)
  if (!post) {
    return NextResponse.json(
      { error: 'Post not found' },
      { status: 404 }
    )
  }
  return NextResponse.json(post)
 }
 export async function PATCH(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
 ) {
  const { id } = await params
  const body = await request.json()
  const updated = await fetch(`https://api.example.com/posts/${id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  }).then(r => r.json())
  return NextResponse.json(updated)
 }
 export async function DELETE(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
 ) {
  const { id } = await params
  await fetch(`https://api.example.com/posts/${id}`, {
    method: 'DELETE',
  })
  return NextResponse.json({ message: 'Post deleted' }, { status: 200 })
 }
 // ============================================================================
 // Example 3: Search with Query Parameters
 // ============================================================================
 // GET /api/search?q=nextjs&limit=10&page=1
 export async function SEARCH(request: Request) {
  const { searchParams } = new URL(request.url)
  const query = searchParams.get('q') || ''
  const limit = parseInt(searchParams.get('limit') || '10')
  const page = parseInt(searchParams.get('page') || '1')
  const offset = (page - 1) * limit
  const results = await fetch(
    `https://api.example.com/search?q=${query}&limit=${limit}&offset=${offset}`
  ).then(r => r.json())
  return NextResponse.json({
    results: results.items,
    total: results.total,
    page,
    limit,
  })
 }
 // ============================================================================
 // Example 4: Authentication with Cookies
 // ============================================================================
 // POST /api/auth/login
 export async function LOGIN(request: Request) {
  const { email, password } = await request.json()
  // Verify credentials
  const user = await fetch('https://api.example.com/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  }).then(r => r.json())
  if (!user.token) {
    return NextResponse.json(
      { error: 'Invalid credentials' },
      { status: 401 }
    )
  }
  // Set cookie
  const response = NextResponse.json({ success: true })
  response.cookies.set('token', user.token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
    maxAge: 60 * 60 * 24 * 7, // 7 days
  })
  return response
 }
 // GET /api/auth/me
 export async function ME() {
  const cookieStore = await cookies() // ✅ Await cookies in Next.js 16
  const token = cookieStore.get('token')?.value
  if (!token) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    )
  }
  const user = await fetch('https://api.example.com/auth/me', {
    headers: { Authorization: `Bearer ${token}` },
  }).then(r => r.json())
  return NextResponse.json(user)
 }
 // ============================================================================
 // Example 5: Webhook Handler
 // ============================================================================
 // File: app/api/webhooks/stripe/route.ts
 import { headers as getHeaders } from 'next/headers'
 export async function WEBHOOK(request: Request) {
  const body = await request.text()
  const headersList = await getHeaders() // ✅ Await headers in Next.js 16
  const signature = headersList.get('stripe-signature')
  if (!signature) {
    return NextResponse.json(
      { error: 'Missing signature' },
      { status: 400 }
    )
  }
  // Verify webhook signature (example with Stripe)
  let event
  try {
    event = JSON.parse(body)
    // In production: stripe.webhooks.constructEvent(body, signature, secret)
  } catch (err) {
    return NextResponse.json(
      { error: 'Invalid payload' },
      { status: 400 }
    )
  }
  // Handle event
  switch (event.type) {
    case 'payment_intent.succeeded':
      await handlePaymentSuccess(event.data.object)
      break
    case 'payment_intent.failed':
      await handlePaymentFailure(event.data.object)
      break
    default:
      console.log(`Unhandled event type: ${event.type}`)
  }
  return NextResponse.json({ received: true })
 }
 async function handlePaymentSuccess(paymentIntent: any) {
  console.log('Payment succeeded:', paymentIntent.id)
  // Update database, send confirmation email, etc.
 }
 async function handlePaymentFailure(paymentIntent: any) {
  console.log('Payment failed:', paymentIntent.id)
  // Notify user, log error, etc.
 }
 // ============================================================================
 // Example 6: Streaming Response
 // ============================================================================
 // GET /api/stream
 export async function STREAM() {
  const encoder = new TextEncoder()
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 10; i++) {
        const data = `data: ${JSON.stringify({ count: i })}\n\n`
        controller.enqueue(encoder.encode(data))
        await new Promise(resolve => setTimeout(resolve, 1000))
      }
      controller.close()
    },
  })
  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  })
 }
 // ============================================================================
 // Example 7: File Upload
 // ============================================================================
 // POST /api/upload
 import { writeFile } from 'fs/promises'
 import { join } from 'path'
 export async function UPLOAD(request: Request) {
  const formData = await request.formData()
  const file = formData.get('file') as File
  if (!file) {
    return NextResponse.json(
      { error: 'No file provided' },
      { status: 400 }
    )
  }
  const bytes = await file.arrayBuffer()
  const buffer = Buffer.from(bytes)
  const filename = `${Date.now()}-${file.name}`
  const path = join(process.cwd(), 'public', 'uploads', filename)
  await writeFile(path, buffer)
  return NextResponse.json({
    success: true,
    url: `/uploads/${filename}`,
  })
 }
 // ============================================================================
 // Example 8: CORS Configuration
 // ============================================================================
 export async function OPTIONS() {
  return new NextResponse(null, {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  })
 }
 export async function CORS_GET() {
  const response = NextResponse.json({ message: 'Hello' })
  response.headers.set('Access-Control-Allow-Origin', '*')
  response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
  response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization')
  return response
 }
 // ============================================================================
 // Example 9: Error Handling
 // ============================================================================
 export async function ERROR_HANDLING() {
  try {
    const data = await fetch('https://api.example.com/data')
      .then(r => {
        if (!r.ok) throw new Error('API request failed')
        return r.json()
      })
    return NextResponse.json(data)
  } catch (error) {
    console.error('Error:', error)
    return NextResponse.json(
      { error: 'Internal Server Error' },
      { status: 500 }
    )
  }
 }
 // ============================================================================
 // Example 10: Rate Limiting
 // ============================================================================
 const rateLimitMap = new Map<string, { count: number; resetAt: number }>()
 export async function RATE_LIMITED() {
  const headersList = await headers()
  const ip = headersList.get('x-forwarded-for') || 'unknown'
  const now = Date.now()
  const rateLimit = rateLimitMap.get(ip)
  if (rateLimit) {
    if (now < rateLimit.resetAt) {
      if (rateLimit.count >= 10) {
        return NextResponse.json(
          { error: 'Too many requests' },
          { status: 429 }
        )
      }
      rateLimit.count++
    } else {
      rateLimitMap.set(ip, { count: 1, resetAt: now + 60000 })
    }
  } else {
    rateLimitMap.set(ip, { count: 1, resetAt: now + 60000 })
  }
  return NextResponse.json({ message: 'Success' })
 }
 /**
 * Summary:
 *
 * Route Handlers (app/api/*/route.ts):
 * 1. ✅ Support all HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
 * 2. ✅ Await params in Next.js 16
 * 3. ✅ Access cookies with await cookies()
 * 4. ✅ Access headers with await headers()
 * 5. ✅ Use NextResponse.json() for JSON responses
 * 6. ✅ Return Response or NextResponse
 *
 * Common patterns:
 * - CRUD operations (GET, POST, PATCH, DELETE)
 * - Query parameters with searchParams
 * - Authentication with cookies
 * - Webhooks with signature verification
 * - Streaming responses (SSE, WebSocket)
 * - File uploads with FormData
 * - CORS configuration
 * - Error handling
 * - Rate limiting
 *
 * Best practices:
 * - Use try/catch for error handling
 * - Return appropriate HTTP status codes
 * - Validate input data
 * - Set secure cookie options in production
 * - Add rate limiting for public endpoints
 * - Use CORS headers when needed
 */
--- a/templates/server-actions-form.tsx
+++ b/templates/server-actions-form.tsx
@@ -0,0 +1,534 @@
 /**
 * Next.js 16 - Server Actions for Form Handling
 *
 * This template shows comprehensive Server Actions patterns including:
 * - Basic form handling
 * - Validation with Zod
 * - Loading states
 * - Error handling
 * - Optimistic updates
 * - File uploads
 */
 'use server'
 import { z } from 'zod'
 import { revalidateTag } from 'next/cache'
 import { redirect } from 'next/navigation'
 // ============================================================================
 // Example 1: Basic Server Action
 // ============================================================================
 export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  const content = formData.get('content') as string
  // Save to database
  await fetch('https://api.example.com/posts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title, content }),
  })
  // Revalidate cache
  revalidateTag('posts', 'max')
  // Redirect to posts list
  redirect('/posts')
 }
 // Basic form component
 export function CreatePostForm() {
  return (
    <form action={createPost}>
      <label>
        Title:
        <input type="text" name="title" required />
      </label>
      <label>
        Content:
        <textarea name="content" required />
      </label>
      <button type="submit">Create Post</button>
    </form>
  )
 }
 // ============================================================================
 // Example 2: Server Action with Validation
 // ============================================================================
 const PostSchema = z.object({
  title: z.string().min(3, 'Title must be at least 3 characters'),
  content: z.string().min(10, 'Content must be at least 10 characters'),
  tags: z.array(z.string()).min(1, 'At least one tag is required'),
 })
 type ActionState = {
  errors?: {
    title?: string[]
    content?: string[]
    tags?: string[]
    _form?: string[]
  }
  success?: boolean
 }
 export async function createPostWithValidation(
  prevState: ActionState,
  formData: FormData
 ): Promise<ActionState> {
  // Parse form data
  const rawData = {
    title: formData.get('title'),
    content: formData.get('content'),
    tags: formData.get('tags')?.toString().split(',') || [],
  }
  // Validate
  const parsed = PostSchema.safeParse(rawData)
  if (!parsed.success) {
    return {
      errors: parsed.error.flatten().fieldErrors,
    }
  }
  // Save to database
  try {
    await fetch('https://api.example.com/posts', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(parsed.data),
    })
    revalidateTag('posts', 'max')
    return { success: true }
  } catch (error) {
    return {
      errors: {
        _form: ['Failed to create post. Please try again.'],
      },
    }
  }
 }
 // Form with validation errors
 'use client'
 import { useFormState, useFormStatus } from 'react-dom'
 function SubmitButton() {
  const { pending } = useFormStatus()
  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Creating...' : 'Create Post'}
    </button>
  )
 }
 export function ValidatedPostForm() {
  const [state, formAction] = useFormState(createPostWithValidation, {})
  return (
    <form action={formAction}>
      <div>
        <label>
          Title:
          <input type="text" name="title" required />
        </label>
        {state.errors?.title && (
          <p className="error">{state.errors.title[0]}</p>
        )}
      </div>
      <div>
        <label>
          Content:
          <textarea name="content" required />
        </label>
        {state.errors?.content && (
          <p className="error">{state.errors.content[0]}</p>
        )}
      </div>
      <div>
        <label>
          Tags (comma-separated):
          <input type="text" name="tags" placeholder="nextjs, react, tutorial" />
        </label>
        {state.errors?.tags && (
          <p className="error">{state.errors.tags[0]}</p>
        )}
      </div>
      {state.errors?._form && (
        <p className="error">{state.errors._form[0]}</p>
      )}
      {state.success && (
        <p className="success">Post created successfully!</p>
      )}
      <SubmitButton />
    </form>
  )
 }
 // ============================================================================
 // Example 3: Server Action with Optimistic Updates
 // ============================================================================
 'use server'
 import { updateTag } from 'next/cache'
 export async function likePost(postId: string) {
  await fetch(`https://api.example.com/posts/${postId}/like`, {
    method: 'POST',
  })
  // Use updateTag for immediate refresh (read-your-writes)
  updateTag('posts')
 }
 // Client component with optimistic updates
 'use client'
 import { useOptimistic } from 'react'
 import { likePost } from './actions'
 export function LikeButton({ postId, initialLikes }: { postId: string; initialLikes: number }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, amount: number) => state + amount
  )
  async function handleLike() {
    // Update UI immediately
    addOptimisticLike(1)
    // Sync with server
    await likePost(postId)
  }
  return (
    <button onClick={handleLike}>
      ❤️ {optimisticLikes} likes
    </button>
  )
 }
 // ============================================================================
 // Example 4: Server Action with File Upload
 // ============================================================================
 'use server'
 import { writeFile } from 'fs/promises'
 import { join } from 'path'
 export async function uploadImage(formData: FormData) {
  const file = formData.get('image') as File
  if (!file) {
    return { error: 'No file provided' }
  }
  // Validate file type
  const validTypes = ['image/jpeg', 'image/png', 'image/webp']
  if (!validTypes.includes(file.type)) {
    return { error: 'Invalid file type. Only JPEG, PNG, and WebP are allowed.' }
  }
  // Validate file size (max 5MB)
  const maxSize = 5 * 1024 * 1024 // 5MB
  if (file.size > maxSize) {
    return { error: 'File too large. Maximum size is 5MB.' }
  }
  // Save file
  const bytes = await file.arrayBuffer()
  const buffer = Buffer.from(bytes)
  const filename = `${Date.now()}-${file.name}`
  const path = join(process.cwd(), 'public', 'uploads', filename)
  await writeFile(path, buffer)
  return {
    success: true,
    url: `/uploads/${filename}`,
  }
 }
 // File upload form
 'use client'
 import { useState } from 'react'
 import { uploadImage } from './actions'
 export function ImageUploadForm() {
  const [preview, setPreview] = useState<string | null>(null)
  const [error, setError] = useState<string | null>(null)
  async function handleSubmit(formData: FormData) {
    const result = await uploadImage(formData)
    if (result.error) {
      setError(result.error)
    } else if (result.url) {
      setPreview(result.url)
      setError(null)
    }
  }
  return (
    <form action={handleSubmit}>
      <input
        type="file"
        name="image"
        accept="image/jpeg,image/png,image/webp"
        required
      />
      <button type="submit">Upload Image</button>
      {error && <p className="error">{error}</p>}
      {preview && (
        <div>
          <h3>Uploaded Image:</h3>
          <img src={preview} alt="Uploaded" width={300} />
        </div>
      )}
    </form>
  )
 }
 // ============================================================================
 // Example 5: Server Action with Progressive Enhancement
 // ============================================================================
 'use server'
 export async function subscribe(formData: FormData) {
  const email = formData.get('email') as string
  await fetch('https://api.example.com/subscribe', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email }),
  })
  return { success: true, message: 'Subscribed successfully!' }
 }
 // Form works without JavaScript (progressive enhancement)
 export function SubscribeForm() {
  return (
    <form action={subscribe}>
      <input
        type="email"
        name="email"
        placeholder="Enter your email"
        required
      />
      <button type="submit">Subscribe</button>
    </form>
  )
 }
 // Enhanced with JavaScript
 'use client'
 import { useFormState } from 'react-dom'
 export function EnhancedSubscribeForm() {
  const [state, formAction] = useFormState(subscribe, null)
  return (
    <form action={formAction}>
      <input
        type="email"
        name="email"
        placeholder="Enter your email"
        required
      />
      <button type="submit">Subscribe</button>
      {state?.success && (
        <p className="success">{state.message}</p>
      )}
    </form>
  )
 }
 // ============================================================================
 // Example 6: Server Action with Multi-Step Form
 // ============================================================================
 'use server'
 type Step1Data = { name: string; email: string }
 type Step2Data = { address: string; city: string }
 type FormData = Step1Data & Step2Data
 export async function submitMultiStepForm(data: FormData) {
  // Validate all data
  const schema = z.object({
    name: z.string().min(2),
    email: z.string().email(),
    address: z.string().min(5),
    city: z.string().min(2),
  })
  const parsed = schema.safeParse(data)
  if (!parsed.success) {
    return {
      errors: parsed.error.flatten().fieldErrors,
    }
  }
  // Save to database
  await fetch('https://api.example.com/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(parsed.data),
  })
  return { success: true }
 }
 // Multi-step form component
 'use client'
 import { useState } from 'react'
 export function MultiStepForm() {
  const [step, setStep] = useState(1)
  const [formData, setFormData] = useState<Partial<FormData>>({})
  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault()
    if (step === 1) {
      const form = e.currentTarget
      setFormData({
        ...formData,
        name: (form.elements.namedItem('name') as HTMLInputElement).value,
        email: (form.elements.namedItem('email') as HTMLInputElement).value,
      })
      setStep(2)
    } else {
      const form = e.currentTarget
      const finalData = {
        ...formData,
        address: (form.elements.namedItem('address') as HTMLInputElement).value,
        city: (form.elements.namedItem('city') as HTMLInputElement).value,
      } as FormData
      const result = await submitMultiStepForm(finalData)
      if (result.success) {
        alert('Form submitted successfully!')
      }
    }
  }
  return (
    <form onSubmit={handleSubmit}>
      {step === 1 && (
        <>
          <h2>Step 1: Personal Info</h2>
          <input name="name" placeholder="Name" defaultValue={formData.name} required />
          <input name="email" type="email" placeholder="Email" defaultValue={formData.email} required />
          <button type="submit">Next</button>
        </>
      )}
      {step === 2 && (
        <>
          <h2>Step 2: Address</h2>
          <input name="address" placeholder="Address" defaultValue={formData.address} required />
          <input name="city" placeholder="City" defaultValue={formData.city} required />
          <button type="button" onClick={() => setStep(1)}>Back</button>
          <button type="submit">Submit</button>
        </>
      )}
    </form>
  )
 }
 // ============================================================================
 // Example 7: Server Action with Rate Limiting
 // ============================================================================
 'use server'
 import { headers } from 'next/headers'
 const rateLimitMap = new Map<string, { count: number; resetAt: number }>()
 export async function submitContactForm(formData: FormData) {
  const headersList = await headers()
  const ip = headersList.get('x-forwarded-for') || 'unknown'
  // Check rate limit (5 requests per hour)
  const now = Date.now()
  const rateLimit = rateLimitMap.get(ip)
  if (rateLimit) {
    if (now < rateLimit.resetAt) {
      if (rateLimit.count >= 5) {
        return { error: 'Too many requests. Please try again later.' }
      }
      rateLimit.count++
    } else {
      // Reset rate limit
      rateLimitMap.set(ip, { count: 1, resetAt: now + 3600000 }) // 1 hour
    }
  } else {
    rateLimitMap.set(ip, { count: 1, resetAt: now + 3600000 })
  }
  // Process form
  const name = formData.get('name') as string
  const message = formData.get('message') as string
  await fetch('https://api.example.com/contact', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name, message }),
  })
  return { success: true }
 }
 /**
 * Summary:
 *
 * Server Actions patterns:
 * 1. ✅ Basic form handling with formData
 * 2. ✅ Validation with Zod (safeParse)
 * 3. ✅ Loading states with useFormStatus
 * 4. ✅ Error handling with useFormState
 * 5. ✅ Optimistic updates with useOptimistic
 * 6. ✅ File uploads
 * 7. ✅ Progressive enhancement (works without JS)
 * 8. ✅ Multi-step forms
 * 9. ✅ Rate limiting
 *
 * Best practices:
 * - Always validate on server (never trust client input)
 * - Use revalidateTag() for background revalidation
 * - Use updateTag() for immediate refresh (forms, settings)
 * - Return errors instead of throwing (better UX)
 * - Use TypeScript for type safety
 * - Add rate limiting for public forms
 */
		`@@ -0,0 +1,3 @@`
							`# nextjs`

							`Build Next.js 16 apps with App Router, Server Components/Actions, Cache Components (use cache), and async route params. Includes proxy.ts (replaces middleware.ts) and React 19.2. Use when: building Next.js 16 projects, or troubleshooting async params (Promise types), use cache directives, parallel route 404s (missing default.js), or proxy.ts CORS.`