autoworkflow 3.9.1 → 3.11.0

package/.claude/skills/nextjs.md

@@ -0,0 +1,2730 @@
+# Next.js Master Skill
+
+> Comprehensive Next.js 14/15 expertise for production-grade applications.
+> This skill covers App Router, Server Components, Server Actions, and advanced patterns.
+
+---
+
+## Table of Contents
+
+1. [Architecture Fundamentals](#architecture-fundamentals)
+2. [Server vs Client Components](#server-vs-client-components)
+3. [Data Fetching Patterns](#data-fetching-patterns)
+4. [Caching Strategies](#caching-strategies)
+5. [Server Actions](#server-actions)
+6. [Route Handlers (API)](#route-handlers-api)
+7. [Middleware](#middleware)
+8. [Streaming & Suspense](#streaming--suspense)
+9. [Error Handling](#error-handling)
+10. [Metadata & SEO](#metadata--seo)
+11. [Authentication Patterns](#authentication-patterns)
+12. [Database Integration](#database-integration)
+13. [Performance Optimization](#performance-optimization)
+14. [Security Best Practices](#security-best-practices)
+15. [Testing Strategies](#testing-strategies)
+16. [Deployment](#deployment)
+17. [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
+18. [File Structure Conventions](#file-structure-conventions)
+
+---
+
+## Architecture Fundamentals
+
+### App Router Structure (Next.js 13+)
+
+```
+app/
+├── layout.tsx              # Root layout (required)
+├── page.tsx                # Home page (/)
+├── loading.tsx             # Loading UI
+├── error.tsx               # Error boundary
+├── not-found.tsx           # 404 page
+├── global-error.tsx        # Root error boundary
+├── template.tsx            # Re-renders on navigation
+├── default.tsx             # Parallel route fallback
+│
+├── (marketing)/            # Route group (no URL impact)
+│   ├── layout.tsx
+│   ├── about/page.tsx
+│   └── contact/page.tsx
+│
+├── dashboard/
+│   ├── layout.tsx
+│   ├── page.tsx
+│   ├── @analytics/         # Parallel route (named slot)
+│   │   └── page.tsx
+│   ├── @team/              # Another parallel route
+│   │   └── page.tsx
+│   └── settings/
+│       └── page.tsx
+│
+├── blog/
+│   ├── page.tsx            # /blog
+│   ├── [slug]/             # Dynamic segment
+│   │   └── page.tsx        # /blog/my-post
+│   └── [...catchAll]/      # Catch-all segment
+│       └── page.tsx        # /blog/2024/01/post
+│
+├── api/                    # Route Handlers
+│   └── webhook/
+│       └── route.ts
+│
+└── _components/            # Private folder (not routed)
+    └── shared.tsx
+```
+
+### Route Segment Config
+
+```typescript
+// Any page.tsx, layout.tsx, or route.ts
+export const dynamic = 'auto' | 'force-dynamic' | 'error' | 'force-static'
+export const dynamicParams = true | false
+export const revalidate = false | 0 | number
+export const fetchCache = 'auto' | 'default-cache' | 'only-cache' | 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'
+export const runtime = 'nodejs' | 'edge'
+export const preferredRegion = 'auto' | 'global' | 'home' | string | string[]
+export const maxDuration = number
+```
+
+---
+
+## Server vs Client Components
+
+### Decision Matrix
+
+| Feature | Server Component | Client Component |
+|---------|------------------|------------------|
+| Fetch data | ✅ Direct DB/API access | ❌ Needs API route |
+| Access backend resources | ✅ Filesystem, DB | ❌ No |
+| Keep secrets secure | ✅ Never sent to client | ❌ Exposed |
+| Reduce bundle size | ✅ Zero JS | ❌ Adds to bundle |
+| useState/useEffect | ❌ No | ✅ Yes |
+| Event handlers (onClick) | ❌ No | ✅ Yes |
+| Browser APIs | ❌ No | ✅ Yes |
+| Custom hooks with state | ❌ No | ✅ Yes |
+| React Context | ❌ No | ✅ Yes |
+
+### Server Component (Default)
+
+```typescript
+// app/dashboard/page.tsx
+// NO "use client" directive = Server Component
+
+import { db } from '@/lib/db'
+import { headers, cookies } from 'next/headers'
+
+export default async function DashboardPage() {
+  // Direct database access - no API needed
+  const user = await db.user.findUnique({
+    where: { id: cookies().get('userId')?.value }
+  })
+
+  // Access request headers
+  const headersList = headers()
+  const userAgent = headersList.get('user-agent')
+
+  // Environment variables (including secrets)
+  const apiKey = process.env.SECRET_API_KEY // Safe - never sent to client
+
+  return (
+    <div>
+      <h1>Welcome, {user?.name}</h1>
+      <ClientInteractiveSection initialData={user} />
+    </div>
+  )
+}
+```
+
+### Client Component
+
+```typescript
+'use client'
+
+// MUST be first line (before imports)
+// This directive marks the boundary - all imports become client components
+
+import { useState, useEffect, useTransition } from 'react'
+import { useRouter, usePathname, useSearchParams } from 'next/navigation'
+
+interface Props {
+  initialData: User
+}
+
+export function ClientInteractiveSection({ initialData }: Props) {
+  const [data, setData] = useState(initialData)
+  const [isPending, startTransition] = useTransition()
+  const router = useRouter()
+  const pathname = usePathname()
+  const searchParams = useSearchParams()
+
+  // Browser APIs available
+  useEffect(() => {
+    const handleResize = () => console.log(window.innerWidth)
+    window.addEventListener('resize', handleResize)
+    return () => window.removeEventListener('resize', handleResize)
+  }, [])
+
+  const handleClick = () => {
+    startTransition(() => {
+      router.refresh() // Revalidate server components
+    })
+  }
+
+  return (
+    <button onClick={handleClick} disabled={isPending}>
+      {isPending ? 'Refreshing...' : 'Refresh Data'}
+    </button>
+  )
+}
+```
+
+### Composition Pattern (Server → Client)
+
+```typescript
+// app/dashboard/page.tsx (Server Component)
+import { ClientTabs } from './client-tabs'
+import { db } from '@/lib/db'
+
+export default async function Page() {
+  const data = await db.analytics.findMany()
+
+  // Pass Server Component as child to Client Component
+  return (
+    <ClientTabs>
+      <ServerRenderedChart data={data} />
+    </ClientTabs>
+  )
+}
+
+// client-tabs.tsx
+'use client'
+import { useState, ReactNode } from 'react'
+
+export function ClientTabs({ children }: { children: ReactNode }) {
+  const [activeTab, setActiveTab] = useState(0)
+
+  return (
+    <div>
+      <button onClick={() => setActiveTab(0)}>Tab 1</button>
+      <button onClick={() => setActiveTab(1)}>Tab 2</button>
+      {activeTab === 0 && children} {/* Server component rendered here */}
+    </div>
+  )
+}
+```
+
+### Provider Pattern
+
+```typescript
+// app/providers.tsx
+'use client'
+
+import { ThemeProvider } from 'next-themes'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { SessionProvider } from 'next-auth/react'
+import { useState } from 'react'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  // Create QueryClient inside component to avoid sharing between requests
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        refetchOnWindowFocus: false,
+      },
+    },
+  }))
+
+  return (
+    <SessionProvider>
+      <QueryClientProvider client={queryClient}>
+        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+          {children}
+        </ThemeProvider>
+      </QueryClientProvider>
+    </SessionProvider>
+  )
+}
+
+// app/layout.tsx (Server Component)
+import { Providers } from './providers'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+---
+
+## Data Fetching Patterns
+
+### Server Component Data Fetching (Recommended)
+
+```typescript
+// app/posts/page.tsx
+import { Suspense } from 'react'
+
+// Parallel data fetching
+async function getPosts() {
+  const res = await fetch('https://api.example.com/posts', {
+    next: { revalidate: 3600 } // Cache for 1 hour
+  })
+  if (!res.ok) throw new Error('Failed to fetch posts')
+  return res.json()
+}
+
+async function getUser() {
+  const res = await fetch('https://api.example.com/user', {
+    cache: 'no-store' // Always fresh
+  })
+  return res.json()
+}
+
+export default async function PostsPage() {
+  // Parallel execution - both start immediately
+  const [posts, user] = await Promise.all([
+    getPosts(),
+    getUser()
+  ])
+
+  return (
+    <div>
+      <UserHeader user={user} />
+      <PostList posts={posts} />
+
+      {/* Defer non-critical data */}
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Comments />
+      </Suspense>
+    </div>
+  )
+}
+
+// Separate component for streaming
+async function Comments() {
+  // This can load after initial page render
+  const comments = await fetch('https://api.example.com/comments', {
+    next: { revalidate: 60 }
+  }).then(r => r.json())
+
+  return <CommentList comments={comments} />
+}
+```
+
+### Fetch Deduplication
+
+```typescript
+// Next.js automatically deduplicates fetch requests with same URL and options
+// across the component tree during a single render
+
+// component-a.tsx
+async function ComponentA() {
+  // This request...
+  const data = await fetch('https://api.example.com/data')
+  return <div>{data.title}</div>
+}
+
+// component-b.tsx
+async function ComponentB() {
+  // ...is deduped with this one (same URL, only 1 request made)
+  const data = await fetch('https://api.example.com/data')
+  return <div>{data.description}</div>
+}
+
+// For non-fetch requests, use React cache()
+import { cache } from 'react'
+import { db } from '@/lib/db'
+
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } })
+})
+
+// Now getUser(id) is deduped across components in same render
+```
+
+### Data Fetching with Preloading
+
+```typescript
+// lib/data.ts
+import { cache } from 'react'
+
+// Wrap in cache for deduplication
+export const getItem = cache(async (id: string) => {
+  const res = await fetch(`https://api.example.com/items/${id}`)
+  return res.json()
+})
+
+// Preload function (call early, don't await)
+export const preloadItem = (id: string) => {
+  void getItem(id)
+}
+
+// page.tsx
+import { getItem, preloadItem } from '@/lib/data'
+
+export default async function Page({ params }: { params: { id: string } }) {
+  // Start fetching immediately
+  preloadItem(params.id)
+
+  // Do other work...
+  const otherData = await getOtherData()
+
+  // Now await - likely already cached
+  const item = await getItem(params.id)
+
+  return <ItemDisplay item={item} />
+}
+```
+
+### Static Generation with Dynamic Params
+
+```typescript
+// app/blog/[slug]/page.tsx
+
+// Generate static paths at build time
+export async function generateStaticParams() {
+  const posts = await fetch('https://api.example.com/posts').then(r => r.json())
+
+  return posts.map((post: Post) => ({
+    slug: post.slug,
+  }))
+}
+
+// Optional: Control behavior for paths not in generateStaticParams
+export const dynamicParams = true // true = generate on-demand, false = 404
+
+export default async function BlogPost({
+  params
+}: {
+  params: { slug: string }
+}) {
+  const post = await fetch(`https://api.example.com/posts/${params.slug}`, {
+    next: { revalidate: 3600 }
+  }).then(r => r.json())
+
+  return <article>{post.content}</article>
+}
+
+// Generate metadata for each page
+export async function generateMetadata({
+  params
+}: {
+  params: { slug: string }
+}): Promise<Metadata> {
+  const post = await getPost(params.slug) // Deduped with page fetch
+
+  return {
+    title: post.title,
+    description: post.excerpt,
+  }
+}
+```
+
+---
+
+## Caching Strategies
+
+### Cache Hierarchy
+
+```
+Request Memoization (React)
+        ↓
+    Data Cache (Next.js)
+        ↓
+    Full Route Cache (Next.js)
+        ↓
+    Router Cache (Client-side)
+```
+
+### Fetch Cache Options
+
+```typescript
+// 1. Force cache (default for GET in production)
+fetch(url, { cache: 'force-cache' })
+fetch(url) // Same as above
+
+// 2. No cache (always fresh)
+fetch(url, { cache: 'no-store' })
+
+// 3. Time-based revalidation
+fetch(url, { next: { revalidate: 3600 } }) // Revalidate every hour
+
+// 4. Tag-based revalidation
+fetch(url, { next: { tags: ['posts', 'user-123'] } })
+
+// Then in Server Action or Route Handler:
+import { revalidateTag, revalidatePath } from 'next/cache'
+
+export async function updatePost() {
+  await db.post.update(...)
+
+  revalidateTag('posts')           // Revalidate all fetches with this tag
+  revalidatePath('/blog')          // Revalidate specific path
+  revalidatePath('/blog', 'layout') // Revalidate layout and all pages below
+  revalidatePath('/blog/[slug]', 'page') // Revalidate dynamic pages
+}
+```
+
+### unstable_cache for Non-Fetch Functions
+
+```typescript
+import { unstable_cache } from 'next/cache'
+import { db } from '@/lib/db'
+
+// Cache database queries
+const getCachedUser = unstable_cache(
+  async (id: string) => {
+    return db.user.findUnique({ where: { id } })
+  },
+  ['user-cache'], // Cache key prefix
+  {
+    tags: ['users'],
+    revalidate: 3600,
+  }
+)
+
+// Usage
+const user = await getCachedUser('user-123')
+
+// Revalidate
+revalidateTag('users')
+```
+
+### Route Segment Caching
+
+```typescript
+// app/dashboard/page.tsx
+
+// Force dynamic rendering (no cache)
+export const dynamic = 'force-dynamic'
+
+// OR force static (error if dynamic features used)
+export const dynamic = 'force-static'
+
+// Set revalidation period for entire route
+export const revalidate = 3600 // seconds
+
+// Disable dynamicParams (404 for unknown params)
+export const dynamicParams = false
+```
+
+---
+
+## Server Actions
+
+### Basic Server Action
+
+```typescript
+// app/actions.ts
+'use server'
+
+import { revalidatePath } from 'next/cache'
+import { redirect } from 'next/navigation'
+import { z } from 'zod'
+import { db } from '@/lib/db'
+import { auth } from '@/lib/auth'
+
+const CreatePostSchema = z.object({
+  title: z.string().min(1).max(100),
+  content: z.string().min(1),
+})
+
+export async function createPost(formData: FormData) {
+  // 1. Authentication
+  const session = await auth()
+  if (!session?.user) {
+    throw new Error('Unauthorized')
+  }
+
+  // 2. Validation
+  const validatedFields = CreatePostSchema.safeParse({
+    title: formData.get('title'),
+    content: formData.get('content'),
+  })
+
+  if (!validatedFields.success) {
+    return {
+      errors: validatedFields.error.flatten().fieldErrors,
+    }
+  }
+
+  // 3. Database operation
+  try {
+    await db.post.create({
+      data: {
+        ...validatedFields.data,
+        authorId: session.user.id,
+      },
+    })
+  } catch (error) {
+    return {
+      error: 'Failed to create post',
+    }
+  }
+
+  // 4. Revalidate and redirect
+  revalidatePath('/posts')
+  redirect('/posts')
+}
+```
+
+### Server Action with useActionState (React 19)
+
+```typescript
+// app/posts/new/page.tsx
+'use client'
+
+import { useActionState } from 'react'
+import { createPost } from '../actions'
+
+const initialState = {
+  errors: {},
+  error: null,
+}
+
+export default function NewPostForm() {
+  const [state, formAction, isPending] = useActionState(createPost, initialState)
+
+  return (
+    <form action={formAction}>
+      <div>
+        <label htmlFor="title">Title</label>
+        <input
+          id="title"
+          name="title"
+          type="text"
+          aria-describedby="title-error"
+        />
+        {state.errors?.title && (
+          <p id="title-error" className="text-red-500">
+            {state.errors.title}
+          </p>
+        )}
+      </div>
+
+      <div>
+        <label htmlFor="content">Content</label>
+        <textarea
+          id="content"
+          name="content"
+          aria-describedby="content-error"
+        />
+        {state.errors?.content && (
+          <p id="content-error" className="text-red-500">
+            {state.errors.content}
+          </p>
+        )}
+      </div>
+
+      {state.error && (
+        <p className="text-red-500">{state.error}</p>
+      )}
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create Post'}
+      </button>
+    </form>
+  )
+}
+```
+
+### Optimistic Updates
+
+```typescript
+'use client'
+
+import { useOptimistic, useTransition } from 'react'
+import { likePost } from './actions'
+
+interface Post {
+  id: string
+  likes: number
+  isLiked: boolean
+}
+
+export function LikeButton({ post }: { post: Post }) {
+  const [isPending, startTransition] = useTransition()
+
+  const [optimisticPost, addOptimisticLike] = useOptimistic(
+    post,
+    (currentPost, newLikes: number) => ({
+      ...currentPost,
+      likes: newLikes,
+      isLiked: !currentPost.isLiked,
+    })
+  )
+
+  const handleLike = () => {
+    startTransition(async () => {
+      // Optimistically update UI
+      addOptimisticLike(optimisticPost.likes + (optimisticPost.isLiked ? -1 : 1))
+
+      // Actual server action
+      await likePost(post.id)
+    })
+  }
+
+  return (
+    <button onClick={handleLike} disabled={isPending}>
+      {optimisticPost.isLiked ? '❤️' : '🤍'} {optimisticPost.likes}
+    </button>
+  )
+}
+```
+
+### Server Action Security Patterns
+
+```typescript
+'use server'
+
+import { auth } from '@/lib/auth'
+import { ratelimit } from '@/lib/ratelimit'
+import { z } from 'zod'
+
+// Rate limiting
+async function checkRateLimit(userId: string) {
+  const { success, remaining } = await ratelimit.limit(userId)
+  if (!success) {
+    throw new Error('Rate limit exceeded')
+  }
+  return remaining
+}
+
+// Authorization check
+async function requireRole(allowedRoles: string[]) {
+  const session = await auth()
+  if (!session?.user) {
+    throw new Error('Unauthorized')
+  }
+  if (!allowedRoles.includes(session.user.role)) {
+    throw new Error('Forbidden')
+  }
+  return session.user
+}
+
+// Secure action pattern
+export async function deletePost(postId: string) {
+  // 1. Auth
+  const user = await requireRole(['admin', 'moderator'])
+
+  // 2. Rate limit
+  await checkRateLimit(user.id)
+
+  // 3. Validate input
+  const id = z.string().uuid().parse(postId)
+
+  // 4. Authorization (ownership check)
+  const post = await db.post.findUnique({ where: { id } })
+  if (!post) throw new Error('Not found')
+  if (post.authorId !== user.id && user.role !== 'admin') {
+    throw new Error('Forbidden')
+  }
+
+  // 5. Perform action
+  await db.post.delete({ where: { id } })
+
+  // 6. Revalidate
+  revalidatePath('/posts')
+}
+```
+
+---
+
+## Route Handlers (API)
+
+### Basic Route Handler
+
+```typescript
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { auth } from '@/lib/auth'
+import { db } from '@/lib/db'
+
+// GET /api/posts
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams
+  const page = parseInt(searchParams.get('page') ?? '1')
+  const limit = parseInt(searchParams.get('limit') ?? '10')
+
+  const posts = await db.post.findMany({
+    skip: (page - 1) * limit,
+    take: limit,
+    orderBy: { createdAt: 'desc' },
+  })
+
+  return NextResponse.json(posts)
+}
+
+// POST /api/posts
+export async function POST(request: NextRequest) {
+  const session = await auth()
+  if (!session) {
+    return NextResponse.json(
+      { error: 'Unauthorized' },
+      { status: 401 }
+    )
+  }
+
+  const body = await request.json()
+
+  const post = await db.post.create({
+    data: {
+      ...body,
+      authorId: session.user.id,
+    },
+  })
+
+  return NextResponse.json(post, { status: 201 })
+}
+
+// Set caching behavior
+export const dynamic = 'force-dynamic' // Disable cache
+// OR
+export const revalidate = 60 // Cache for 60 seconds
+```
+
+### Dynamic Route Handler
+
+```typescript
+// app/api/posts/[id]/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+
+interface RouteParams {
+  params: { id: string }
+}
+
+export async function GET(
+  request: NextRequest,
+  { params }: RouteParams
+) {
+  const post = await db.post.findUnique({
+    where: { id: params.id },
+  })
+
+  if (!post) {
+    return NextResponse.json(
+      { error: 'Not found' },
+      { status: 404 }
+    )
+  }
+
+  return NextResponse.json(post)
+}
+
+export async function PATCH(
+  request: NextRequest,
+  { params }: RouteParams
+) {
+  const body = await request.json()
+
+  const post = await db.post.update({
+    where: { id: params.id },
+    data: body,
+  })
+
+  return NextResponse.json(post)
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: RouteParams
+) {
+  await db.post.delete({
+    where: { id: params.id },
+  })
+
+  return new NextResponse(null, { status: 204 })
+}
+```
+
+### Streaming Response
+
+```typescript
+// app/api/stream/route.ts
+import { NextRequest } from 'next/server'
+
+export async function GET(request: NextRequest) {
+  const encoder = new TextEncoder()
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      for (let i = 0; i < 10; i++) {
+        const chunk = encoder.encode(`data: ${JSON.stringify({ count: i })}\n\n`)
+        controller.enqueue(chunk)
+        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',
+    },
+  })
+}
+```
+
+### Webhook Handler
+
+```typescript
+// app/api/webhook/stripe/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { headers } from 'next/headers'
+import Stripe from 'stripe'
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
+const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!
+
+export async function POST(request: NextRequest) {
+  const body = await request.text()
+  const signature = headers().get('stripe-signature')!
+
+  let event: Stripe.Event
+
+  try {
+    event = stripe.webhooks.constructEvent(body, signature, webhookSecret)
+  } catch (err) {
+    console.error('Webhook signature verification failed')
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
+  }
+
+  switch (event.type) {
+    case 'checkout.session.completed':
+      const session = event.data.object as Stripe.Checkout.Session
+      await handleCheckoutComplete(session)
+      break
+    case 'customer.subscription.deleted':
+      const subscription = event.data.object as Stripe.Subscription
+      await handleSubscriptionCanceled(subscription)
+      break
+    default:
+      console.log(`Unhandled event type: ${event.type}`)
+  }
+
+  return NextResponse.json({ received: true })
+}
+```
+
+---
+
+## Middleware
+
+### Basic Middleware
+
+```typescript
+// middleware.ts (root of project)
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  // Get pathname
+  const pathname = request.nextUrl.pathname
+
+  // Example: Redirect old URLs
+  if (pathname.startsWith('/old-blog')) {
+    return NextResponse.redirect(
+      new URL(pathname.replace('/old-blog', '/blog'), request.url)
+    )
+  }
+
+  // Example: Add custom headers
+  const response = NextResponse.next()
+  response.headers.set('x-custom-header', 'my-value')
+
+  // Example: Rewrite (internal redirect)
+  if (pathname === '/dashboard' && !request.cookies.get('auth')) {
+    return NextResponse.rewrite(new URL('/login', request.url))
+  }
+
+  return response
+}
+
+// Configure which paths middleware runs on
+export const config = {
+  matcher: [
+    // Match all paths except static files and api
+    '/((?!_next/static|_next/image|favicon.ico|api).*)',
+  ],
+}
+```
+
+### Authentication Middleware
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+import { getToken } from 'next-auth/jwt'
+
+const protectedRoutes = ['/dashboard', '/settings', '/profile']
+const authRoutes = ['/login', '/register']
+
+export async function middleware(request: NextRequest) {
+  const token = await getToken({
+    req: request,
+    secret: process.env.NEXTAUTH_SECRET,
+  })
+
+  const pathname = request.nextUrl.pathname
+
+  // Redirect authenticated users away from auth pages
+  if (authRoutes.some(route => pathname.startsWith(route))) {
+    if (token) {
+      return NextResponse.redirect(new URL('/dashboard', request.url))
+    }
+    return NextResponse.next()
+  }
+
+  // Protect routes
+  if (protectedRoutes.some(route => pathname.startsWith(route))) {
+    if (!token) {
+      const loginUrl = new URL('/login', request.url)
+      loginUrl.searchParams.set('callbackUrl', pathname)
+      return NextResponse.redirect(loginUrl)
+    }
+  }
+
+  // Role-based access
+  if (pathname.startsWith('/admin')) {
+    if (token?.role !== 'admin') {
+      return NextResponse.redirect(new URL('/unauthorized', request.url))
+    }
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: [
+    '/dashboard/:path*',
+    '/settings/:path*',
+    '/profile/:path*',
+    '/admin/:path*',
+    '/login',
+    '/register',
+  ],
+}
+```
+
+### Geolocation & A/B Testing
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  // Geolocation (available on Vercel Edge)
+  const country = request.geo?.country ?? 'US'
+  const city = request.geo?.city ?? 'Unknown'
+
+  // A/B Testing
+  let bucket = request.cookies.get('ab-bucket')?.value
+
+  if (!bucket) {
+    bucket = Math.random() < 0.5 ? 'control' : 'variant'
+  }
+
+  const response = NextResponse.next()
+
+  // Set headers for downstream use
+  response.headers.set('x-country', country)
+  response.headers.set('x-city', city)
+  response.headers.set('x-ab-bucket', bucket)
+
+  // Set cookie for consistent bucketing
+  response.cookies.set('ab-bucket', bucket, {
+    maxAge: 60 * 60 * 24 * 30, // 30 days
+  })
+
+  return response
+}
+```
+
+---
+
+## Streaming & Suspense
+
+### Loading UI with Suspense
+
+```typescript
+// app/dashboard/page.tsx
+import { Suspense } from 'react'
+import { Skeleton } from '@/components/ui/skeleton'
+
+export default function DashboardPage() {
+  return (
+    <div className="grid gap-4">
+      {/* Critical content - renders immediately */}
+      <DashboardHeader />
+
+      {/* Non-critical - streams in */}
+      <Suspense fallback={<StatsSkeleton />}>
+        <Stats />
+      </Suspense>
+
+      <div className="grid grid-cols-2 gap-4">
+        <Suspense fallback={<ChartSkeleton />}>
+          <RevenueChart />
+        </Suspense>
+
+        <Suspense fallback={<ChartSkeleton />}>
+          <UserChart />
+        </Suspense>
+      </div>
+
+      <Suspense fallback={<TableSkeleton />}>
+        <RecentOrders />
+      </Suspense>
+    </div>
+  )
+}
+
+// Each async component streams independently
+async function Stats() {
+  const stats = await getStats() // Slow API call
+  return <StatsDisplay stats={stats} />
+}
+
+async function RevenueChart() {
+  const data = await getRevenueData()
+  return <Chart data={data} />
+}
+```
+
+### Loading.tsx (Route-level Loading)
+
+```typescript
+// app/dashboard/loading.tsx
+// Automatically wraps page.tsx in Suspense
+
+import { Skeleton } from '@/components/ui/skeleton'
+
+export default function DashboardLoading() {
+  return (
+    <div className="space-y-4">
+      <Skeleton className="h-8 w-[200px]" />
+      <div className="grid grid-cols-4 gap-4">
+        {Array.from({ length: 4 }).map((_, i) => (
+          <Skeleton key={i} className="h-24" />
+        ))}
+      </div>
+      <Skeleton className="h-[400px]" />
+    </div>
+  )
+}
+```
+
+### Parallel Routes with Loading States
+
+```typescript
+// app/dashboard/layout.tsx
+export default function DashboardLayout({
+  children,
+  analytics,
+  team,
+}: {
+  children: React.ReactNode
+  analytics: React.ReactNode  // @analytics/page.tsx
+  team: React.ReactNode       // @team/page.tsx
+}) {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      <div className="col-span-2">{children}</div>
+      <div className="space-y-4">
+        {analytics}
+        {team}
+      </div>
+    </div>
+  )
+}
+
+// app/dashboard/@analytics/loading.tsx
+export default function AnalyticsLoading() {
+  return <Skeleton className="h-[200px]" />
+}
+
+// app/dashboard/@team/loading.tsx
+export default function TeamLoading() {
+  return <Skeleton className="h-[150px]" />
+}
+```
+
+### Streaming with AI/LLM
+
+```typescript
+// app/api/chat/route.ts
+import { OpenAIStream, StreamingTextResponse } from 'ai'
+import OpenAI from 'openai'
+
+const openai = new OpenAI()
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4-turbo-preview',
+    stream: true,
+    messages,
+  })
+
+  const stream = OpenAIStream(response)
+
+  return new StreamingTextResponse(stream)
+}
+
+// Client component
+'use client'
+
+import { useChat } from 'ai/react'
+
+export function Chat() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat()
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Say something..."
+          disabled={isLoading}
+        />
+      </form>
+    </div>
+  )
+}
+```
+
+---
+
+## Error Handling
+
+### Error Boundary (error.tsx)
+
+```typescript
+// app/dashboard/error.tsx
+'use client' // Error boundaries must be client components
+
+import { useEffect } from 'react'
+import { Button } from '@/components/ui/button'
+
+export default function DashboardError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  useEffect(() => {
+    // Log error to monitoring service
+    console.error('Dashboard error:', error)
+
+    // Send to Sentry, etc.
+    // Sentry.captureException(error)
+  }, [error])
+
+  return (
+    <div className="flex flex-col items-center justify-center min-h-[400px] gap-4">
+      <h2 className="text-2xl font-bold">Something went wrong!</h2>
+      <p className="text-muted-foreground">
+        {error.message || 'An unexpected error occurred'}
+      </p>
+      {error.digest && (
+        <p className="text-xs text-muted-foreground">
+          Error ID: {error.digest}
+        </p>
+      )}
+      <Button onClick={reset}>Try again</Button>
+    </div>
+  )
+}
+```
+
+### Global Error Boundary
+
+```typescript
+// app/global-error.tsx
+'use client'
+
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  return (
+    // Must include html and body tags
+    <html>
+      <body>
+        <div className="flex flex-col items-center justify-center min-h-screen">
+          <h2>Something went wrong!</h2>
+          <button onClick={reset}>Try again</button>
+        </div>
+      </body>
+    </html>
+  )
+}
+```
+
+### Not Found Handling
+
+```typescript
+// app/not-found.tsx
+import Link from 'next/link'
+
+export default function NotFound() {
+  return (
+    <div className="flex flex-col items-center justify-center min-h-[400px]">
+      <h2 className="text-2xl font-bold">Page Not Found</h2>
+      <p className="text-muted-foreground">
+        The page you're looking for doesn't exist.
+      </p>
+      <Link href="/" className="mt-4 underline">
+        Go home
+      </Link>
+    </div>
+  )
+}
+
+// Trigger not-found programmatically
+import { notFound } from 'next/navigation'
+
+export default async function PostPage({ params }: { params: { id: string } }) {
+  const post = await getPost(params.id)
+
+  if (!post) {
+    notFound() // Renders not-found.tsx
+  }
+
+  return <PostDisplay post={post} />
+}
+```
+
+### Error Handling in Server Actions
+
+```typescript
+'use server'
+
+import { z } from 'zod'
+
+// Type-safe error responses
+type ActionResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: string; fieldErrors?: Record<string, string[]> }
+
+export async function createUser(formData: FormData): Promise<ActionResult<User>> {
+  try {
+    const validated = UserSchema.safeParse({
+      email: formData.get('email'),
+      name: formData.get('name'),
+    })
+
+    if (!validated.success) {
+      return {
+        success: false,
+        error: 'Validation failed',
+        fieldErrors: validated.error.flatten().fieldErrors,
+      }
+    }
+
+    const user = await db.user.create({ data: validated.data })
+
+    return { success: true, data: user }
+  } catch (error) {
+    // Log error
+    console.error('Create user error:', error)
+
+    // Return generic error (don't expose internal details)
+    return {
+      success: false,
+      error: 'Failed to create user. Please try again.'
+    }
+  }
+}
+```
+
+---
+
+## Metadata & SEO
+
+### Static Metadata
+
+```typescript
+// app/layout.tsx
+import type { Metadata } from 'next'
+
+export const metadata: Metadata = {
+  metadataBase: new URL('https://example.com'),
+  title: {
+    default: 'My App',
+    template: '%s | My App', // Pages can override: "About | My App"
+  },
+  description: 'The best app ever',
+  keywords: ['Next.js', 'React', 'TypeScript'],
+  authors: [{ name: 'John Doe', url: 'https://johndoe.com' }],
+  creator: 'John Doe',
+  publisher: 'My Company',
+
+  // Open Graph
+  openGraph: {
+    type: 'website',
+    locale: 'en_US',
+    url: 'https://example.com',
+    siteName: 'My App',
+    title: 'My App',
+    description: 'The best app ever',
+    images: [
+      {
+        url: '/og-image.png',
+        width: 1200,
+        height: 630,
+        alt: 'My App',
+      },
+    ],
+  },
+
+  // Twitter
+  twitter: {
+    card: 'summary_large_image',
+    title: 'My App',
+    description: 'The best app ever',
+    creator: '@johndoe',
+    images: ['/twitter-image.png'],
+  },
+
+  // Robots
+  robots: {
+    index: true,
+    follow: true,
+    googleBot: {
+      index: true,
+      follow: true,
+      'max-video-preview': -1,
+      'max-image-preview': 'large',
+      'max-snippet': -1,
+    },
+  },
+
+  // Icons
+  icons: {
+    icon: '/favicon.ico',
+    shortcut: '/favicon-16x16.png',
+    apple: '/apple-touch-icon.png',
+  },
+
+  // Manifest
+  manifest: '/site.webmanifest',
+
+  // Verification
+  verification: {
+    google: 'google-site-verification-code',
+    yandex: 'yandex-verification-code',
+  },
+}
+```
+
+### Dynamic Metadata
+
+```typescript
+// app/blog/[slug]/page.tsx
+import type { Metadata, ResolvingMetadata } from 'next'
+
+interface Props {
+  params: { slug: string }
+  searchParams: { [key: string]: string | string[] | undefined }
+}
+
+export async function generateMetadata(
+  { params, searchParams }: Props,
+  parent: ResolvingMetadata
+): Promise<Metadata> {
+  const post = await getPost(params.slug)
+
+  // Optionally access parent metadata
+  const previousImages = (await parent).openGraph?.images || []
+
+  return {
+    title: post.title,
+    description: post.excerpt,
+    openGraph: {
+      title: post.title,
+      description: post.excerpt,
+      type: 'article',
+      publishedTime: post.createdAt,
+      authors: [post.author.name],
+      images: [
+        {
+          url: post.image,
+          width: 1200,
+          height: 630,
+        },
+        ...previousImages,
+      ],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title: post.title,
+      description: post.excerpt,
+      images: [post.image],
+    },
+  }
+}
+```
+
+### JSON-LD Structured Data
+
+```typescript
+// app/blog/[slug]/page.tsx
+
+export default async function BlogPost({ params }: Props) {
+  const post = await getPost(params.slug)
+
+  const jsonLd = {
+    '@context': 'https://schema.org',
+    '@type': 'BlogPosting',
+    headline: post.title,
+    description: post.excerpt,
+    image: post.image,
+    datePublished: post.createdAt,
+    dateModified: post.updatedAt,
+    author: {
+      '@type': 'Person',
+      name: post.author.name,
+      url: post.author.url,
+    },
+    publisher: {
+      '@type': 'Organization',
+      name: 'My Company',
+      logo: {
+        '@type': 'ImageObject',
+        url: 'https://example.com/logo.png',
+      },
+    },
+  }
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+      <article>{/* content */}</article>
+    </>
+  )
+}
+```
+
+### Sitemap & Robots
+
+```typescript
+// app/sitemap.ts
+import { MetadataRoute } from 'next'
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const posts = await db.post.findMany({
+    select: { slug: true, updatedAt: true },
+  })
+
+  const postUrls = posts.map((post) => ({
+    url: `https://example.com/blog/${post.slug}`,
+    lastModified: post.updatedAt,
+    changeFrequency: 'weekly' as const,
+    priority: 0.8,
+  }))
+
+  return [
+    {
+      url: 'https://example.com',
+      lastModified: new Date(),
+      changeFrequency: 'daily',
+      priority: 1,
+    },
+    {
+      url: 'https://example.com/about',
+      lastModified: new Date(),
+      changeFrequency: 'monthly',
+      priority: 0.5,
+    },
+    ...postUrls,
+  ]
+}
+
+// app/robots.ts
+import { MetadataRoute } from 'next'
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      {
+        userAgent: '*',
+        allow: '/',
+        disallow: ['/api/', '/admin/', '/private/'],
+      },
+      {
+        userAgent: 'Googlebot',
+        allow: '/',
+      },
+    ],
+    sitemap: 'https://example.com/sitemap.xml',
+  }
+}
+```
+
+---
+
+## Authentication Patterns
+
+### NextAuth.js v5 Setup
+
+```typescript
+// auth.ts
+import NextAuth from 'next-auth'
+import GitHub from 'next-auth/providers/github'
+import Google from 'next-auth/providers/google'
+import Credentials from 'next-auth/providers/credentials'
+import { PrismaAdapter } from '@auth/prisma-adapter'
+import { db } from '@/lib/db'
+import bcrypt from 'bcryptjs'
+
+export const { auth, handlers, signIn, signOut } = NextAuth({
+  adapter: PrismaAdapter(db),
+  session: { strategy: 'jwt' },
+
+  providers: [
+    GitHub({
+      clientId: process.env.GITHUB_ID,
+      clientSecret: process.env.GITHUB_SECRET,
+    }),
+    Google({
+      clientId: process.env.GOOGLE_ID,
+      clientSecret: process.env.GOOGLE_SECRET,
+    }),
+    Credentials({
+      credentials: {
+        email: { label: 'Email', type: 'email' },
+        password: { label: 'Password', type: 'password' },
+      },
+      async authorize(credentials) {
+        if (!credentials?.email || !credentials?.password) {
+          return null
+        }
+
+        const user = await db.user.findUnique({
+          where: { email: credentials.email as string },
+        })
+
+        if (!user || !user.password) {
+          return null
+        }
+
+        const isValid = await bcrypt.compare(
+          credentials.password as string,
+          user.password
+        )
+
+        if (!isValid) {
+          return null
+        }
+
+        return {
+          id: user.id,
+          email: user.email,
+          name: user.name,
+          role: user.role,
+        }
+      },
+    }),
+  ],
+
+  callbacks: {
+    async jwt({ token, user, trigger, session }) {
+      if (user) {
+        token.id = user.id
+        token.role = user.role
+      }
+
+      // Handle session update
+      if (trigger === 'update' && session) {
+        token.name = session.name
+      }
+
+      return token
+    },
+
+    async session({ session, token }) {
+      if (session.user) {
+        session.user.id = token.id as string
+        session.user.role = token.role as string
+      }
+      return session
+    },
+
+    async signIn({ user, account, profile }) {
+      // Block sign in if email not verified
+      if (account?.provider === 'credentials') {
+        const existingUser = await db.user.findUnique({
+          where: { id: user.id },
+        })
+        if (!existingUser?.emailVerified) {
+          return false
+        }
+      }
+      return true
+    },
+  },
+
+  pages: {
+    signIn: '/login',
+    error: '/auth/error',
+    verifyRequest: '/auth/verify',
+  },
+})
+
+// app/api/auth/[...nextauth]/route.ts
+import { handlers } from '@/auth'
+export const { GET, POST } = handlers
+```
+
+### Protected Server Component
+
+```typescript
+// app/dashboard/page.tsx
+import { auth } from '@/auth'
+import { redirect } from 'next/navigation'
+
+export default async function DashboardPage() {
+  const session = await auth()
+
+  if (!session) {
+    redirect('/login')
+  }
+
+  // Role-based check
+  if (session.user.role !== 'admin') {
+    redirect('/unauthorized')
+  }
+
+  return (
+    <div>
+      <h1>Welcome, {session.user.name}</h1>
+    </div>
+  )
+}
+```
+
+### Protected Client Component
+
+```typescript
+'use client'
+
+import { useSession } from 'next-auth/react'
+import { useRouter } from 'next/navigation'
+import { useEffect } from 'react'
+
+export function ProtectedComponent() {
+  const { data: session, status } = useSession()
+  const router = useRouter()
+
+  useEffect(() => {
+    if (status === 'unauthenticated') {
+      router.push('/login')
+    }
+  }, [status, router])
+
+  if (status === 'loading') {
+    return <div>Loading...</div>
+  }
+
+  if (!session) {
+    return null
+  }
+
+  return <div>Protected content for {session.user.name}</div>
+}
+```
+
+### Sign In/Out Server Actions
+
+```typescript
+// app/actions/auth.ts
+'use server'
+
+import { signIn, signOut } from '@/auth'
+import { AuthError } from 'next-auth'
+import { redirect } from 'next/navigation'
+
+export async function signInWithCredentials(formData: FormData) {
+  try {
+    await signIn('credentials', {
+      email: formData.get('email'),
+      password: formData.get('password'),
+      redirectTo: '/dashboard',
+    })
+  } catch (error) {
+    if (error instanceof AuthError) {
+      switch (error.type) {
+        case 'CredentialsSignin':
+          return { error: 'Invalid credentials' }
+        default:
+          return { error: 'Something went wrong' }
+      }
+    }
+    throw error
+  }
+}
+
+export async function signInWithGitHub() {
+  await signIn('github', { redirectTo: '/dashboard' })
+}
+
+export async function signOutAction() {
+  await signOut({ redirectTo: '/' })
+}
+```
+
+---
+
+## Database Integration
+
+### Prisma Setup
+
+```typescript
+// lib/db.ts
+import { PrismaClient } from '@prisma/client'
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined
+}
+
+export const db = globalForPrisma.prisma ?? new PrismaClient({
+  log: process.env.NODE_ENV === 'development'
+    ? ['query', 'error', 'warn']
+    : ['error'],
+})
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = db
+}
+```
+
+### Drizzle ORM Setup
+
+```typescript
+// lib/db.ts
+import { drizzle } from 'drizzle-orm/postgres-js'
+import postgres from 'postgres'
+import * as schema from './schema'
+
+const connectionString = process.env.DATABASE_URL!
+
+// For query purposes
+const queryClient = postgres(connectionString)
+export const db = drizzle(queryClient, { schema })
+
+// lib/schema.ts
+import { pgTable, text, timestamp, uuid, boolean } from 'drizzle-orm/pg-core'
+
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  email: text('email').notNull().unique(),
+  name: text('name'),
+  emailVerified: timestamp('email_verified'),
+  image: text('image'),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+})
+
+export const posts = pgTable('posts', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  title: text('title').notNull(),
+  content: text('content'),
+  published: boolean('published').default(false).notNull(),
+  authorId: uuid('author_id').references(() => users.id).notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+})
+```
+
+### Database Query Patterns
+
+```typescript
+// lib/queries/posts.ts
+import { cache } from 'react'
+import { db } from '@/lib/db'
+import { unstable_cache } from 'next/cache'
+
+// Request-level caching (deduplication)
+export const getPost = cache(async (id: string) => {
+  return db.post.findUnique({
+    where: { id },
+    include: { author: true },
+  })
+})
+
+// Time-based caching
+export const getPublishedPosts = unstable_cache(
+  async () => {
+    return db.post.findMany({
+      where: { published: true },
+      orderBy: { createdAt: 'desc' },
+      include: { author: { select: { name: true, image: true } } },
+    })
+  },
+  ['published-posts'],
+  { revalidate: 3600, tags: ['posts'] }
+)
+
+// Pagination
+export async function getPaginatedPosts(page: number, limit: number = 10) {
+  const [posts, total] = await Promise.all([
+    db.post.findMany({
+      skip: (page - 1) * limit,
+      take: limit,
+      orderBy: { createdAt: 'desc' },
+    }),
+    db.post.count(),
+  ])
+
+  return {
+    posts,
+    total,
+    pages: Math.ceil(total / limit),
+    hasMore: page * limit < total,
+  }
+}
+```
+
+---
+
+## Performance Optimization
+
+### Image Optimization
+
+```typescript
+import Image from 'next/image'
+
+// Basic usage
+<Image
+  src="/hero.jpg"
+  alt="Hero image"
+  width={1200}
+  height={600}
+  priority // Load immediately (above the fold)
+/>
+
+// Fill container
+<div className="relative h-64 w-full">
+  <Image
+    src="/background.jpg"
+    alt="Background"
+    fill
+    className="object-cover"
+    sizes="100vw"
+  />
+</div>
+
+// Responsive images
+<Image
+  src="/photo.jpg"
+  alt="Photo"
+  width={800}
+  height={600}
+  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+  placeholder="blur"
+  blurDataURL="data:image/jpeg;base64,..." // Or use static import for auto blur
+/>
+
+// Remote images (configure in next.config.js)
+// next.config.js
+module.exports = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'cdn.example.com',
+        pathname: '/images/**',
+      },
+    ],
+  },
+}
+```
+
+### Font Optimization
+
+```typescript
+// app/layout.tsx
+import { Inter, Roboto_Mono } from 'next/font/google'
+import localFont from 'next/font/local'
+
+// Google Fonts
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-inter',
+})
+
+const robotoMono = Roboto_Mono({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-roboto-mono',
+})
+
+// Local fonts
+const customFont = localFont({
+  src: [
+    {
+      path: '../fonts/CustomFont-Regular.woff2',
+      weight: '400',
+      style: 'normal',
+    },
+    {
+      path: '../fonts/CustomFont-Bold.woff2',
+      weight: '700',
+      style: 'normal',
+    },
+  ],
+  variable: '--font-custom',
+})
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${robotoMono.variable} ${customFont.variable}`}>
+      <body className="font-sans">{children}</body>
+    </html>
+  )
+}
+
+// tailwind.config.ts
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['var(--font-inter)'],
+        mono: ['var(--font-roboto-mono)'],
+        custom: ['var(--font-custom)'],
+      },
+    },
+  },
+}
+```
+
+### Bundle Analysis
+
+```bash
+# Install analyzer
+npm install @next/bundle-analyzer
+
+# next.config.js
+const withBundleAnalyzer = require('@next/bundle-analyzer')({
+  enabled: process.env.ANALYZE === 'true',
+})
+
+module.exports = withBundleAnalyzer({
+  // your config
+})
+
+# Run analysis
+ANALYZE=true npm run build
+```
+
+### Dynamic Imports
+
+```typescript
+import dynamic from 'next/dynamic'
+
+// Basic dynamic import
+const DynamicComponent = dynamic(() => import('./HeavyComponent'), {
+  loading: () => <p>Loading...</p>,
+})
+
+// Disable SSR (for browser-only components)
+const MapComponent = dynamic(() => import('./Map'), {
+  ssr: false,
+  loading: () => <MapSkeleton />,
+})
+
+// Named exports
+const Modal = dynamic(() =>
+  import('./Modal').then((mod) => mod.Modal)
+)
+
+// Usage
+export default function Page() {
+  return (
+    <div>
+      <DynamicComponent />
+      <MapComponent />
+    </div>
+  )
+}
+```
+
+---
+
+## Security Best Practices
+
+### Environment Variables
+
+```typescript
+// ❌ Wrong - exposes to client
+const apiKey = process.env.API_KEY // undefined on client
+
+// ✅ Correct - server only
+const apiKey = process.env.API_KEY // Only in Server Components/Actions/Route Handlers
+
+// ✅ Correct - exposed to client (prefix with NEXT_PUBLIC_)
+const publicKey = process.env.NEXT_PUBLIC_STRIPE_KEY // Available everywhere
+
+// lib/env.ts - Validate environment variables
+import { z } from 'zod'
+
+const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  NEXTAUTH_SECRET: z.string().min(32),
+  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+})
+
+export const env = envSchema.parse(process.env)
+```
+
+### Content Security Policy
+
+```typescript
+// next.config.js
+const ContentSecurityPolicy = `
+  default-src 'self';
+  script-src 'self' 'unsafe-eval' 'unsafe-inline' https://cdn.example.com;
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' blob: data: https://cdn.example.com;
+  font-src 'self';
+  connect-src 'self' https://api.example.com;
+  frame-ancestors 'none';
+`
+
+const securityHeaders = [
+  {
+    key: 'Content-Security-Policy',
+    value: ContentSecurityPolicy.replace(/\s{2,}/g, ' ').trim(),
+  },
+  {
+    key: 'X-Frame-Options',
+    value: 'DENY',
+  },
+  {
+    key: 'X-Content-Type-Options',
+    value: 'nosniff',
+  },
+  {
+    key: 'Referrer-Policy',
+    value: 'strict-origin-when-cross-origin',
+  },
+  {
+    key: 'Permissions-Policy',
+    value: 'camera=(), microphone=(), geolocation=()',
+  },
+]
+
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: '/:path*',
+        headers: securityHeaders,
+      },
+    ]
+  },
+}
+```
+
+### Input Validation
+
+```typescript
+// lib/validations/post.ts
+import { z } from 'zod'
+
+export const createPostSchema = z.object({
+  title: z
+    .string()
+    .min(1, 'Title is required')
+    .max(100, 'Title must be less than 100 characters')
+    .transform((val) => val.trim()),
+  content: z
+    .string()
+    .min(1, 'Content is required')
+    .max(10000, 'Content must be less than 10000 characters'),
+  tags: z
+    .array(z.string().max(20))
+    .max(5, 'Maximum 5 tags allowed')
+    .optional(),
+})
+
+export type CreatePostInput = z.infer<typeof createPostSchema>
+
+// Server Action
+'use server'
+
+import { createPostSchema } from '@/lib/validations/post'
+import { auth } from '@/auth'
+import DOMPurify from 'isomorphic-dompurify'
+
+export async function createPost(input: unknown) {
+  const session = await auth()
+  if (!session) throw new Error('Unauthorized')
+
+  // Validate input
+  const validated = createPostSchema.parse(input)
+
+  // Sanitize HTML content if allowing rich text
+  const sanitizedContent = DOMPurify.sanitize(validated.content, {
+    ALLOWED_TAGS: ['p', 'b', 'i', 'em', 'strong', 'a', 'ul', 'ol', 'li'],
+    ALLOWED_ATTR: ['href'],
+  })
+
+  return db.post.create({
+    data: {
+      ...validated,
+      content: sanitizedContent,
+      authorId: session.user.id,
+    },
+  })
+}
+```
+
+### CSRF Protection
+
+```typescript
+// Server Actions have built-in CSRF protection via the Origin header check
+
+// For API Routes, implement manually:
+// app/api/webhook/route.ts
+import { headers } from 'next/headers'
+import crypto from 'crypto'
+
+export async function POST(request: Request) {
+  const headersList = headers()
+  const signature = headersList.get('x-webhook-signature')
+
+  if (!signature) {
+    return new Response('Missing signature', { status: 401 })
+  }
+
+  const body = await request.text()
+  const expectedSignature = crypto
+    .createHmac('sha256', process.env.WEBHOOK_SECRET!)
+    .update(body)
+    .digest('hex')
+
+  if (!crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expectedSignature)
+  )) {
+    return new Response('Invalid signature', { status: 401 })
+  }
+
+  // Process webhook...
+}
+```
+
+---
+
+## Testing Strategies
+
+### Unit Testing with Vitest
+
+```typescript
+// __tests__/utils.test.ts
+import { describe, it, expect } from 'vitest'
+import { formatDate, slugify } from '@/lib/utils'
+
+describe('formatDate', () => {
+  it('formats date correctly', () => {
+    const date = new Date('2024-01-15')
+    expect(formatDate(date)).toBe('January 15, 2024')
+  })
+})
+
+describe('slugify', () => {
+  it('converts string to slug', () => {
+    expect(slugify('Hello World')).toBe('hello-world')
+    expect(slugify('Test 123!')).toBe('test-123')
+  })
+})
+```
+
+### Component Testing with React Testing Library
+
+```typescript
+// __tests__/components/Button.test.tsx
+import { render, screen, fireEvent } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import { Button } from '@/components/ui/button'
+
+describe('Button', () => {
+  it('renders children correctly', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByRole('button')).toHaveTextContent('Click me')
+  })
+
+  it('calls onClick when clicked', () => {
+    const handleClick = vi.fn()
+    render(<Button onClick={handleClick}>Click me</Button>)
+
+    fireEvent.click(screen.getByRole('button'))
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('is disabled when disabled prop is true', () => {
+    render(<Button disabled>Click me</Button>)
+    expect(screen.getByRole('button')).toBeDisabled()
+  })
+})
+```
+
+### Integration Testing with Playwright
+
+```typescript
+// tests/e2e/auth.spec.ts
+import { test, expect } from '@playwright/test'
+
+test.describe('Authentication', () => {
+  test('should redirect to login when accessing protected route', async ({ page }) => {
+    await page.goto('/dashboard')
+    await expect(page).toHaveURL('/login?callbackUrl=%2Fdashboard')
+  })
+
+  test('should login successfully with valid credentials', async ({ page }) => {
+    await page.goto('/login')
+
+    await page.fill('input[name="email"]', 'test@example.com')
+    await page.fill('input[name="password"]', 'password123')
+    await page.click('button[type="submit"]')
+
+    await expect(page).toHaveURL('/dashboard')
+    await expect(page.locator('h1')).toContainText('Welcome')
+  })
+
+  test('should show error with invalid credentials', async ({ page }) => {
+    await page.goto('/login')
+
+    await page.fill('input[name="email"]', 'wrong@example.com')
+    await page.fill('input[name="password"]', 'wrongpassword')
+    await page.click('button[type="submit"]')
+
+    await expect(page.locator('[data-testid="error-message"]')).toBeVisible()
+  })
+})
+```
+
+### API Route Testing
+
+```typescript
+// __tests__/api/posts.test.ts
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { GET, POST } from '@/app/api/posts/route'
+import { db } from '@/lib/db'
+
+vi.mock('@/lib/db')
+vi.mock('@/auth', () => ({
+  auth: vi.fn(() => Promise.resolve({ user: { id: '1' } })),
+}))
+
+describe('POST /api/posts', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('creates a post successfully', async () => {
+    const mockPost = { id: '1', title: 'Test', content: 'Content' }
+    vi.mocked(db.post.create).mockResolvedValue(mockPost)
+
+    const request = new Request('http://localhost/api/posts', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'Test', content: 'Content' }),
+    })
+
+    const response = await POST(request)
+    const data = await response.json()
+
+    expect(response.status).toBe(201)
+    expect(data).toEqual(mockPost)
+  })
+})
+```
+
+---
+
+## Deployment
+
+### Vercel Configuration
+
+```json
+// vercel.json
+{
+  "buildCommand": "prisma generate && next build",
+  "framework": "nextjs",
+  "regions": ["iad1"],
+  "env": {
+    "DATABASE_URL": "@database-url",
+    "NEXTAUTH_SECRET": "@nextauth-secret"
+  },
+  "crons": [
+    {
+      "path": "/api/cron/cleanup",
+      "schedule": "0 0 * * *"
+    }
+  ]
+}
+```
+
+### Docker Deployment
+
+```dockerfile
+# Dockerfile
+FROM node:20-alpine AS base
+
+# Install dependencies only when needed
+FROM base AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm ci
+
+# Rebuild the source code only when needed
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+ENV NEXT_TELEMETRY_DISABLED 1
+
+RUN npx prisma generate
+RUN npm run build
+
+# Production image
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV production
+ENV NEXT_TELEMETRY_DISABLED 1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+
+ENV PORT 3000
+ENV HOSTNAME "0.0.0.0"
+
+CMD ["node", "server.js"]
+```
+
+```javascript
+// next.config.js for standalone output
+module.exports = {
+  output: 'standalone',
+}
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### 1. Fetching in Client Components Unnecessarily
+
+```typescript
+// ❌ Bad - unnecessary client-side fetch
+'use client'
+export function Posts() {
+  const [posts, setPosts] = useState([])
+
+  useEffect(() => {
+    fetch('/api/posts').then(r => r.json()).then(setPosts)
+  }, [])
+
+  return <PostList posts={posts} />
+}
+
+// ✅ Good - fetch in Server Component
+export default async function Posts() {
+  const posts = await db.post.findMany()
+  return <PostList posts={posts} />
+}
+```
+
+### 2. Waterfall Requests
+
+```typescript
+// ❌ Bad - sequential fetches
+async function Page() {
+  const user = await getUser()
+  const posts = await getPosts()  // Waits for user
+  const comments = await getComments()  // Waits for posts
+  return <Content user={user} posts={posts} comments={comments} />
+}
+
+// ✅ Good - parallel fetches
+async function Page() {
+  const [user, posts, comments] = await Promise.all([
+    getUser(),
+    getPosts(),
+    getComments(),
+  ])
+  return <Content user={user} posts={posts} comments={comments} />
+}
+```
+
+### 3. Passing Functions as Props to Client Components
+
+```typescript
+// ❌ Bad - can't serialize functions
+async function Page() {
+  async function handleSubmit(data: FormData) {
+    'use server'
+    await db.post.create({ data })
+  }
+
+  return <Form onSubmit={handleSubmit} /> // Error!
+}
+
+// ✅ Good - import Server Action
+import { createPost } from './actions'
+
+export default function Page() {
+  return <Form action={createPost} />
+}
+```
+
+### 4. Using useEffect for Data Fetching
+
+```typescript
+// ❌ Bad - client-side fetch with useEffect
+'use client'
+function Dashboard() {
+  const [data, setData] = useState(null)
+
+  useEffect(() => {
+    fetchData().then(setData)
+  }, [])
+
+  if (!data) return <Loading />
+  return <DashboardContent data={data} />
+}
+
+// ✅ Good - Server Component with Suspense
+async function Dashboard() {
+  const data = await fetchData()
+  return <DashboardContent data={data} />
+}
+
+// Wrap in Suspense at parent level
+<Suspense fallback={<Loading />}>
+  <Dashboard />
+</Suspense>
+```
+
+### 5. Overusing 'use client'
+
+```typescript
+// ❌ Bad - entire page is client
+'use client'
+export default function Page() {
+  const [count, setCount] = useState(0)
+  const data = useData() // Client-side fetch
+
+  return (
+    <div>
+      <Header />
+      <Navigation />
+      <Content data={data} />
+      <Counter count={count} setCount={setCount} />
+      <Footer />
+    </div>
+  )
+}
+
+// ✅ Good - only interactive parts are client
+export default async function Page() {
+  const data = await getData() // Server fetch
+
+  return (
+    <div>
+      <Header />
+      <Navigation />
+      <Content data={data} />
+      <Counter /> {/* Only this is 'use client' */}
+      <Footer />
+    </div>
+  )
+}
+```
+
+### 6. Not Handling Loading States
+
+```typescript
+// ❌ Bad - no loading state
+export default async function Page() {
+  const data = await slowFetch() // User sees blank page
+  return <Content data={data} />
+}
+
+// ✅ Good - with loading state
+// loading.tsx
+export default function Loading() {
+  return <Skeleton />
+}
+
+// page.tsx
+export default async function Page() {
+  const data = await slowFetch()
+  return <Content data={data} />
+}
+```
+
+---
+
+## File Structure Conventions
+
+### Recommended Structure
+
+```
+src/
+├── app/                      # App Router
+│   ├── (auth)/              # Auth route group
+│   │   ├── login/
+│   │   └── register/
+│   ├── (marketing)/         # Marketing route group
+│   │   ├── about/
+│   │   └── pricing/
+│   ├── (dashboard)/         # Dashboard route group
+│   │   ├── layout.tsx
+│   │   ├── dashboard/
+│   │   └── settings/
+│   ├── api/                 # Route Handlers
+│   ├── layout.tsx
+│   ├── page.tsx
+│   ├── loading.tsx
+│   ├── error.tsx
+│   ├── not-found.tsx
+│   └── providers.tsx
+│
+├── components/
+│   ├── ui/                  # Shadcn/UI components
+│   │   ├── button.tsx
+│   │   ├── input.tsx
+│   │   └── dialog.tsx
+│   ├── forms/               # Form components
+│   │   ├── login-form.tsx
+│   │   └── post-form.tsx
+│   ├── layouts/             # Layout components
+│   │   ├── header.tsx
+│   │   ├── footer.tsx
+│   │   └── sidebar.tsx
+│   └── [feature]/           # Feature-specific components
+│       ├── post-card.tsx
+│       └── post-list.tsx
+│
+├── lib/
+│   ├── db.ts               # Database client
+│   ├── auth.ts             # Auth configuration
+│   ├── utils.ts            # Utility functions
+│   └── validations/        # Zod schemas
+│       ├── auth.ts
+│       └── post.ts
+│
+├── hooks/                   # Custom React hooks
+│   ├── use-media-query.ts
+│   └── use-debounce.ts
+│
+├── actions/                 # Server Actions
+│   ├── auth.ts
+│   ├── posts.ts
+│   └── users.ts
+│
+├── types/                   # TypeScript types
+│   ├── index.d.ts
+│   └── next-auth.d.ts
+│
+├── styles/
+│   └── globals.css
+│
+└── config/
+    ├── site.ts             # Site configuration
+    └── dashboard.ts        # Dashboard navigation
+```
+
+---
+
+## Quick Reference
+
+### Common Imports
+
+```typescript
+// Navigation
+import { redirect, notFound } from 'next/navigation'
+import { useRouter, usePathname, useSearchParams } from 'next/navigation'
+import Link from 'next/link'
+
+// Headers/Cookies
+import { headers, cookies } from 'next/headers'
+
+// Caching
+import { revalidatePath, revalidateTag } from 'next/cache'
+import { unstable_cache } from 'next/cache'
+import { cache } from 'react'
+
+// Images/Fonts
+import Image from 'next/image'
+import { Inter } from 'next/font/google'
+
+// Dynamic
+import dynamic from 'next/dynamic'
+
+// Metadata
+import type { Metadata, ResolvingMetadata } from 'next'
+```
+
+### Essential Patterns Cheat Sheet
+
+| Pattern | Use Case |
+|---------|----------|
+| `async function Component()` | Server Component data fetching |
+| `'use client'` | Interactive components |
+| `'use server'` | Server Actions |
+| `<Suspense>` | Streaming/loading states |
+| `loading.tsx` | Route-level loading UI |
+| `error.tsx` | Route-level error boundary |
+| `generateStaticParams` | Static generation for dynamic routes |
+| `generateMetadata` | Dynamic SEO metadata |
+| `revalidatePath/Tag` | On-demand revalidation |
+| `unstable_cache` | Cache non-fetch functions |
+| `cache()` | Request memoization |
+
+---
+
+*This skill provides comprehensive Next.js expertise. Reference specific sections as needed during development.*