Nextjs Developer

Next.js Developer Skill

Overview

This skill provides comprehensive expertise in building production-ready Next.js applications using the App Router (Next.js 15+). It covers Server Components, React 19 support, data fetching patterns, routing, API routes, caching, and performance optimization.

Core Capabilities

App Router Architecture

• Server Components: Default rendering model for optimal performance
• Client Components: Interactive components with "use client" directive
• Layouts: Shared UI with preserved state across routes
• Templates: Fresh instances on navigation (no state preservation)
• Loading UI: Streaming with loading.tsx files
• Error Handling: Granular error boundaries with error.tsx

Data Fetching

• Server-side fetching: Direct database/API access in Server Components
• Caching strategies: Dynamic rendering by default, explicit caching, and incremental regeneration
• Revalidation: Time-based and on-demand cache invalidation
• Parallel fetching: Optimized data loading patterns

Routing System

• File-based routing: Automatic route generation from file structure
• Dynamic routes: [param] and catch-all [...slug] patterns
• Route groups: (folder) for organization without URL impact
• Parallel routes: @slot for simultaneous route rendering
• Intercepting routes: Modal patterns with (.), (..), (...)

Server Actions

• Form handling: Progressive enhancement with action attribute
• Mutations: Server-side data modifications
• Revalidation: Automatic cache updates after mutations
• Optimistic updates: Immediate UI feedback patterns

Implementation Patterns

Project Structure

app/
├── layout.tsx          # Root layout
├── page.tsx            # Home page
├── globals.css         # Global styles
├── (auth)/             # Route group
│   ├── login/page.tsx
│   └── register/page.tsx
├── dashboard/
│   ├── layout.tsx      # Dashboard layout
│   ├── page.tsx        # Dashboard home
│   ├── loading.tsx     # Loading UI
│   ├── error.tsx       # Error boundary
│   └── [id]/page.tsx   # Dynamic route
├── api/
│   └── [route]/route.ts # API routes
└── components/         # Shared components

Component Patterns

Server Component (Default)

// app/posts/page.tsx
async function PostsPage() {
  const posts = await db.posts.findMany()

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

export default PostsPage

Client Component

// app/components/counter.tsx
"use client"

import { useState } from "react"

export function Counter() {
  const [count, setCount] = useState(0)

  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  )
}

Data Fetching Patterns

Dynamic Rendering (Default)

// In Next.js 15+, fetch is uncached by default (implicit cache: 'no-store')
async function Page() {
  const data = await fetch('https://api.example.com/data')
  return <div>{data}</div>
}

Static Generation (Opt-in)

// Explicitly opt into caching
async function Page() {
  const data = await fetch('https://api.example.com/data', {
    cache: 'force-cache',
  })
  return <div>{data}</div>
}

Time-based Revalidation

async function Page() {
  const data = await fetch('https://api.example.com/data', {
    next: { revalidate: 3600 }, // Revalidate every hour
  })
  return <div>{data}</div>
}

Note: The client router cache is also uncached by default in Next.js 15, replacing the old 30s/5m defaults.

Server Actions

// app/actions.ts
"use server"

import { revalidatePath } from "next/cache"

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

  await db.posts.create({ data: { title } })

  revalidatePath("/posts")
}

// app/posts/new/page.tsx
import { createPost } from "@/app/actions"

export default function NewPost() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <button type="submit">Create</button>
    </form>
  )
}

Partial Prerendering (PPR)

• PPR combines a static shell with dynamic streaming in a single HTTP request.
• It is production-ready in Next.js 15+ and was experimental in Next.js 14.
• Enable incremental adoption with experimental.ppr: 'incremental' in next.config.js, or use ppr: true when you want full PPR.
• Use Suspense boundaries to define dynamic holes inside static shells.
• Adopt PPR route by route so you can gradually expand coverage without rewriting the whole app.

// app/page.tsx — static shell with dynamic hole
export const experimental_ppr = true

export default function Page() {
  return (
    <main>
      <StaticHeader />
      <Suspense fallback={<ProductSkeleton />}>
        <DynamicProductList />
      </Suspense>
    </main>
  )
}

Turbopack

• Turbopack is stable for next dev in Next.js 15 and for next build in Next.js 15.3+.
• The production build path passes 8,298 test suite cases.
• Use next dev --turbopack and next build --turbopack to opt in.
• It can be up to 10x faster than Webpack for dev server startup.
• Some Webpack loaders and plugins may still need migration work.

next dev --turbopack
next build --turbopack

React 19 Features

• React 19 is the default runtime in Next.js 15+ App Router projects.
• Use use() to consume promises and contexts during render.
• Server Actions are stable and no longer experimental.
• Use useFormStatus() for form state without prop drilling.
• Use useOptimistic() for optimistic UI updates.

import { use } from "react"
import { useFormStatus } from "react-dom"
import { useOptimistic } from "react"

function ProductName({ productPromise }: { productPromise: Promise<{ name: string }> }) {
  const product = use(productPromise)
  return <h1>{product.name}</h1>
}

after() Post-Response Work

• Next.js 15 introduces after() for post-response work.
• Use it for logging, analytics, and other non-critical tasks after the response is sent.
• Import it from next/server.

import { after } from 'next/server'

after(() => {
  logAnalytics()
})

Navigation Hooks (Next.js 15.4)

• useLinkStatus() helps show inline link-loading indicators.
• onNavigate lets you track or block client-side navigation.
• useLinkStatus() is a client hook from next/link and returns { pending }.
• onNavigate is a Link prop for SPA navigations only.

'use client'

import Link, { useLinkStatus } from 'next/link'

function LinkHint() {
  const { pending } = useLinkStatus()
  return <span aria-hidden>{pending ? 'Loading…' : null}</span>
}

export function Nav() {
  return (
    <nav>
      <Link href="/dashboard" prefetch={false} onNavigate={() => trackNavigation('/dashboard')}>
        Dashboard <LinkHint />
      </Link>
    </nav>
  )
}

next.config.js Patterns

• Keep experimental flags only when needed; several features have graduated to stable in Next.js 15+.
• Use experimental.ppr: 'incremental' for route-by-route PPR adoption.
• Use ppr: true only when you want a fully PPR-enabled app.
• Turbopack is enabled via CLI flags, not a next.config.js switch.

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

const nextConfig: NextConfig = {
  experimental: {
    ppr: 'incremental',
  },
  // For full PPR:
  // ppr: true,
}

export default nextConfig

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack"
  }
}

Best Practices

Performance

• Use Server Components by default
• Prefer dynamic rendering unless you explicitly need caching
• Use PPR for fast static shells with dynamic holes
• Optimize images with next/image
• Use next/font for font optimization
• Implement streaming with Suspense boundaries

Security

• Validate all inputs in Server Actions
• Use environment variables for secrets
• Implement proper authentication patterns
• Sanitize user-generated content

Code Organization

• Colocate components with routes when possible
• Use route groups for logical organization
• Implement proper error boundaries
• Create reusable layout patterns

Scripts

This skill includes executable scripts in the scripts/ folder:

Development

• dev-server.sh: Start the development server with hot reloading

  ./scripts/dev-server.sh [--port PORT] [--turbo]

• build-production.sh: Create optimized production build

  ./scripts/build-production.sh [--analyze]

• analyze-bundle.sh: Analyze bundle size and dependencies

  ./scripts/analyze-bundle.sh

Code Generation

• create-page.sh: Generate a new page with optional layout/loading/error files

  ./scripts/create-page.sh <page-path> [--layout] [--loading] [--error]

• create-api-route.sh: Generate API route handlers

  ./scripts/create-api-route.sh <route-name> [--dynamic]

• create-component.sh: Generate React components with optional tests

  ./scripts/create-component.sh <name> [--client] [--test] [--dir DIR]

Testing

• setup-testing.sh: Set up Jest and React Testing Library

  ./scripts/setup-testing.sh [--playwright]

• run-tests.sh: Run tests with various options

  ./scripts/run-tests.sh [--watch] [--coverage] [--file FILE]

Templates

This skill includes production-ready templates in the templates/ folder:

Pages

• page-server.tsx: Server Component page with async data fetching, metadata, and Suspense streaming
• page-client.tsx: Client Component page with state management, hooks, and interactivity
• page-dynamic.tsx: Dynamic route page with params, generateStaticParams, and generateMetadata

Components

• component-server.tsx: Server Component with data fetching and composition patterns
• component-client.tsx: Client Component with hooks, event handlers, and localStorage

API & Backend

• api-route.ts: Complete API route handler with CRUD, validation (Zod), auth, and CORS
• server-action.ts: Server Actions with form handling, validation, and revalidation
• middleware.ts: Middleware with auth, rate limiting, i18n, and security headers

Infrastructure

• layout.tsx: Root/nested layout with navigation, footer, metadata, and fonts
• page.test.tsx: Testing patterns for pages, components, API routes, and Server Actions

Resources

This skill includes detailed reference guides in the resources/ folder:

• app-router-patterns.md: Comprehensive App Router patterns and examples
• data-fetching.md: Data fetching strategies and caching
• server-components.md: Server vs Client Components guide
• routing-reference.md: Complete routing system reference
• performance-optimization.md: Performance best practices
• api-routes.md: API route handlers and patterns
• testing-patterns.md: Testing strategies for Next.js apps

---

Specialization: Next.js App Router Development Version: 2.0 Last Updated: May 2026

Next.js API Routes (Route Handlers)

Overview

Route Handlers allow you to create custom request handlers for a given route using the Web Request and Response APIs.

---

Basic Structure

File Convention

app/
└── api/
    ├── route.ts              # /api
    ├── posts/
    │   └── route.ts          # /api/posts
    └── posts/
        └── [id]/
            └── route.ts      # /api/posts/[id]

HTTP Methods

// app/api/posts/route.ts
export async function GET(request: Request) {}
export async function POST(request: Request) {}
export async function PUT(request: Request) {}
export async function PATCH(request: Request) {}
export async function DELETE(request: Request) {}
export async function HEAD(request: Request) {}
export async function OPTIONS(request: Request) {}

---

Request Handling

Reading Request Body

export async function POST(request: Request) {
  const body = await request.json()

  return Response.json({
    received: body,
  })
}

Form Data

export async function POST(request: Request) {
  const formData = await request.formData()
  const name = formData.get("name")
  const email = formData.get("email")

  return Response.json({ name, email })
}

URL Search Params

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const query = searchParams.get("q")
  const page = searchParams.get("page") || "1"

  return Response.json({ query, page })
}

Headers

import { headers } from "next/headers"

export async function GET() {
  const headersList = headers()
  const authorization = headersList.get("authorization")

  return Response.json({ authorization })
}

Cookies

import { cookies } from "next/headers"

export async function GET() {
  const cookieStore = cookies()
  const token = cookieStore.get("token")

  return Response.json({ token: token?.value })
}

export async function POST() {
  const cookieStore = cookies()

  cookieStore.set("session", "abc123", {
    httpOnly: true,
    secure: true,
    sameSite: "strict",
    maxAge: 60 * 60 * 24, // 1 day
  })

  return Response.json({ success: true })
}

---

Response Handling

JSON Response

export async function GET() {
  return Response.json({ message: "Hello" })
}

// With status code
export async function POST() {
  return Response.json(
    { message: "Created" },
    { status: 201 }
  )
}

Using NextResponse

import { NextResponse } from "next/server"

export async function GET() {
  return NextResponse.json(
    { message: "Hello" },
    {
      status: 200,
      headers: {
        "Cache-Control": "max-age=3600",
      },
    }
  )
}

Redirects

import { redirect } from "next/navigation"
import { NextResponse } from "next/server"

export async function GET() {
  // Option 1: Using redirect function
  redirect("/new-location")

  // Option 2: Using NextResponse
  return NextResponse.redirect(new URL("/new-location", request.url))
}

Streaming Response

export async function GET() {
  const encoder = new TextEncoder()

  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 10; i++) {
        controller.enqueue(encoder.encode(`data: ${i}\n\n`))
        await new Promise((r) => setTimeout(r, 100))
      }
      controller.close()
    },
  })

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      Connection: "keep-alive",
    },
  })
}

---

Dynamic Routes

Single Parameter

// app/api/posts/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const post = await getPost(params.id)

  if (!post) {
    return Response.json(
      { error: "Not found" },
      { status: 404 }
    )
  }

  return Response.json(post)
}

Multiple Parameters

// app/api/users/[userId]/posts/[postId]/route.ts
export async function GET(
  request: Request,
  { params }: { params: { userId: string; postId: string } }
) {
  const { userId, postId } = params
  const post = await getUserPost(userId, postId)

  return Response.json(post)
}

Catch-All Routes

// app/api/[...slug]/route.ts
export async function GET(
  request: Request,
  { params }: { params: { slug: string[] } }
) {
  // /api/a/b/c -> slug = ['a', 'b', 'c']
  const path = params.slug.join("/")

  return Response.json({ path })
}

---

CORS

// app/api/route.ts
const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization",
}

export async function OPTIONS() {
  return Response.json({}, { headers: corsHeaders })
}

export async function GET() {
  return Response.json(
    { message: "Hello" },
    { headers: corsHeaders }
  )
}

---

Caching

Static Route Handler

// Cached by default when using GET with no dynamic features
export async function GET() {
  const data = await fetch("https://api.example.com/data")
  return Response.json(data)
}

Opt Out of Caching

// Option 1: Use Request object
export async function GET(request: Request) {
  // Using request opts out of caching
  return Response.json({ time: Date.now() })
}

// Option 2: Route segment config
export const dynamic = "force-dynamic"

export async function GET() {
  return Response.json({ time: Date.now() })
}

Revalidation

export const revalidate = 3600 // Revalidate every hour

export async function GET() {
  const data = await fetch("https://api.example.com/data")
  return Response.json(data)
}

---

Error Handling

Basic Error Handling

export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  try {
    const post = await getPost(params.id)

    if (!post) {
      return Response.json(
        { error: "Post not found" },
        { status: 404 }
      )
    }

    return Response.json(post)
  } catch (error) {
    console.error("Error fetching post:", error)

    return Response.json(
      { error: "Internal server error" },
      { status: 500 }
    )
  }
}

Validation Error

import { z } from "zod"

const postSchema = z.object({
  title: z.string().min(1).max(100),
  content: z.string().min(1),
})

export async function POST(request: Request) {
  try {
    const body = await request.json()
    const data = postSchema.parse(body)

    const post = await createPost(data)
    return Response.json(post, { status: 201 })
  } catch (error) {
    if (error instanceof z.ZodError) {
      return Response.json(
        { error: "Validation failed", details: error.errors },
        { status: 400 }
      )
    }

    return Response.json(
      { error: "Internal server error" },
      { status: 500 }
    )
  }
}

---

Authentication

Protected Route

import { getServerSession } from "next-auth"
import { authOptions } from "@/lib/auth"

export async function GET() {
  const session = await getServerSession(authOptions)

  if (!session) {
    return Response.json(
      { error: "Unauthorized" },
      { status: 401 }
    )
  }

  return Response.json({ user: session.user })
}

API Key Authentication

export async function GET(request: Request) {
  const apiKey = request.headers.get("x-api-key")

  if (apiKey !== process.env.API_KEY) {
    return Response.json(
      { error: "Invalid API key" },
      { status: 401 }
    )
  }

  return Response.json({ data: "protected data" })
}

---

File Uploads

export async function POST(request: Request) {
  const formData = await request.formData()
  const file = formData.get("file") as File

  if (!file) {
    return Response.json(
      { error: "No file provided" },
      { status: 400 }
    )
  }

  const bytes = await file.arrayBuffer()
  const buffer = Buffer.from(bytes)

  // Save to filesystem or cloud storage
  const path = `/uploads/${file.name}`
  await writeFile(path, buffer)

  return Response.json({ path })
}

---

Webhooks

import crypto from "crypto"

export async function POST(request: Request) {
  const body = await request.text()
  const signature = request.headers.get("x-webhook-signature")

  // Verify signature
  const expectedSignature = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(body)
    .digest("hex")

  if (signature !== expectedSignature) {
    return Response.json(
      { error: "Invalid signature" },
      { status: 401 }
    )
  }

  const event = JSON.parse(body)

  // Process webhook event
  await processWebhookEvent(event)

  return Response.json({ received: true })
}

---

Best Practices

Structure

• Group related endpoints in folders
• Use descriptive route names
• Keep handlers focused and simple

Security

• Validate all inputs
• Use proper authentication
• Sanitize responses (don't leak sensitive data)
• Implement rate limiting

Performance

• Use appropriate caching
• Optimize database queries
• Return early on errors

Error Handling

• Return appropriate status codes
• Provide helpful error messages
• Log errors for debugging

---

Last Updated: January 2026

Next.js App Router Patterns

File Conventions

The App Router uses a file-system based router where folders define routes and special files define UI.

Special Files

---

Layout Patterns

Root Layout (Required)

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

Nested Layout

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <div className="dashboard">
      <nav>
        <a href="/dashboard">Overview</a>
        <a href="/dashboard/settings">Settings</a>
      </nav>
      <main>{children}</main>
    </div>
  )
}

Layout with Metadata

// app/blog/layout.tsx
import type { Metadata } from "next"

export const metadata: Metadata = {
  title: {
    template: "%s | Blog",
    default: "Blog",
  },
}

export default function BlogLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return <section>{children}</section>
}

---

Loading States

Basic Loading UI

// app/dashboard/loading.tsx
export default function Loading() {
  return <div className="skeleton">Loading...</div>
}

Loading with Suspense Boundaries

// app/dashboard/page.tsx
import { Suspense } from "react"

async function SlowComponent() {
  const data = await fetch("/api/slow")
  return <div>{data}</div>
}

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<div>Loading stats...</div>}>
        <SlowComponent />
      </Suspense>
    </div>
  )
}

---

Error Handling

Error Boundary

// app/dashboard/error.tsx
"use client"

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Global Error Handler

// app/global-error.tsx
"use client"

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

Not Found Page

// app/not-found.tsx
import Link from "next/link"

export default function NotFound() {
  return (
    <div>
      <h2>Not Found</h2>
      <p>Could not find the requested resource</p>
      <Link href="/">Return Home</Link>
    </div>
  )
}

---

Route Groups

Route groups allow organizing routes without affecting the URL structure.

Organizing by Feature

app/
├── (marketing)/
│   ├── about/page.tsx      # /about
│   └── blog/page.tsx       # /blog
├── (shop)/
│   ├── products/page.tsx   # /products
│   └── cart/page.tsx       # /cart
└── layout.tsx

Multiple Root Layouts

app/
├── (marketing)/
│   ├── layout.tsx          # Marketing layout
│   └── page.tsx
├── (app)/
│   ├── layout.tsx          # App layout
│   └── dashboard/page.tsx

---

Parallel Routes

Parallel routes allow rendering multiple pages in the same layout simultaneously.

Basic Parallel Routes

app/
├── @analytics/
│   └── page.tsx
├── @team/
│   └── page.tsx
├── layout.tsx
└── page.tsx

// app/layout.tsx
export default function Layout({
  children,
  analytics,
  team,
}: {
  children: React.ReactNode
  analytics: React.ReactNode
  team: React.ReactNode
}) {
  return (
    <div>
      {children}
      <div className="sidebar">
        {analytics}
        {team}
      </div>
    </div>
  )
}

Conditional Rendering with Parallel Routes

// app/layout.tsx
import { getUser } from "@/lib/auth"

export default async function Layout({
  children,
  admin,
  user,
}: {
  children: React.ReactNode
  admin: React.ReactNode
  user: React.ReactNode
}) {
  const currentUser = await getUser()

  return (
    <div>
      {currentUser.role === "admin" ? admin : user}
      {children}
    </div>
  )
}

---

Intercepting Routes

Intercepting routes allow loading a route within the current layout.

Convention

• (.) - Match same level
• (..) - Match one level above
• (..)(..) - Match two levels above
• (...) - Match from root

Modal Pattern

app/
├── @modal/
│   └── (.)photo/[id]/page.tsx  # Intercepted route (modal)
├── photo/
│   └── [id]/page.tsx           # Direct access (full page)
├── layout.tsx
└── page.tsx

// app/@modal/(.)photo/[id]/page.tsx
import { Modal } from "@/components/modal"

export default function PhotoModal({
  params,
}: {
  params: { id: string }
}) {
  return (
    <Modal>
      <img src={`/photos/${params.id}`} alt="" />
    </Modal>
  )
}

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

---

Template Pattern

Templates create a new instance on navigation (unlike layouts).

// app/template.tsx
export default function Template({
  children,
}: {
  children: React.ReactNode
}) {
  return <div className="fade-in">{children}</div>
}

Use Cases:

• Enter/exit animations
• Features relying on useEffect (logging page views)
• Features relying on useState (per-page feedback form)

---

Metadata Patterns

Static Metadata

// app/page.tsx
import type { Metadata } from "next"

export const metadata: Metadata = {
  title: "Home",
  description: "Welcome to our website",
  openGraph: {
    title: "Home",
    description: "Welcome to our website",
    images: ["/og-image.jpg"],
  },
}

Dynamic Metadata

// app/posts/[id]/page.tsx
import type { Metadata, ResolvingMetadata } from "next"

type Props = {
  params: { id: string }
}

export async function generateMetadata(
  { params }: Props,
  parent: ResolvingMetadata
): Promise<Metadata> {
  const post = await getPost(params.id)

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      images: [post.image, ...(await parent).openGraph?.images || []],
    },
  }
}

---

Last Updated: January 2026

Next.js Data Fetching Guide

Overview

Next.js App Router provides powerful data fetching capabilities with automatic caching and revalidation.

---

Server Component Data Fetching

Basic Fetch

// app/posts/page.tsx
async function getPosts() {
  const res = await fetch("https://api.example.com/posts")

  if (!res.ok) {
    throw new Error("Failed to fetch posts")
  }

  return res.json()
}

export default async function PostsPage() {
  const posts = await getPosts()

  return (
    <ul>
      {posts.map((post: Post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

Direct Database Access

// app/users/page.tsx
import { db } from "@/lib/db"

export default async function UsersPage() {
  const users = await db.user.findMany()

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  )
}

---

Caching Strategies

Static Data (Default)

// Cached indefinitely until revalidated
async function getData() {
  const res = await fetch("https://api.example.com/data")
  return res.json()
}

Dynamic Data (No Cache)

// Never cached, always fresh
async function getData() {
  const res = await fetch("https://api.example.com/data", {
    cache: "no-store",
  })
  return res.json()
}

Time-based Revalidation

// Revalidate every hour
async function getData() {
  const res = await fetch("https://api.example.com/data", {
    next: { revalidate: 3600 },
  })
  return res.json()
}

---

Route Segment Config

Force Dynamic Rendering

// app/dashboard/page.tsx
export const dynamic = "force-dynamic"
// Options: 'auto' | 'force-dynamic' | 'error' | 'force-static'

Revalidation at Route Level

// app/blog/page.tsx
export const revalidate = 3600 // Revalidate every hour
// Use 0 for no caching, false to cache indefinitely

Dynamic Params

// app/posts/[id]/page.tsx
export const dynamicParams = true // Allow params not in generateStaticParams
// false = return 404 for unknown params

---

On-Demand Revalidation

Revalidate by Path

// app/api/revalidate/route.ts
import { revalidatePath } from "next/cache"
import { NextRequest } from "next/server"

export async function POST(request: NextRequest) {
  const path = request.nextUrl.searchParams.get("path")

  if (path) {
    revalidatePath(path)
    return Response.json({ revalidated: true, now: Date.now() })
  }

  return Response.json({
    revalidated: false,
    message: "Missing path param",
  })
}

Revalidate by Tag

// Fetch with tag
async function getPosts() {
  const res = await fetch("https://api.example.com/posts", {
    next: { tags: ["posts"] },
  })
  return res.json()
}

// Revalidate the tag
import { revalidateTag } from "next/cache"

export async function POST() {
  revalidateTag("posts")
  return Response.json({ revalidated: true })
}

---

Parallel Data Fetching

Using Promise.all

// app/dashboard/page.tsx
async function getUser(userId: string) {
  const res = await fetch(`/api/users/${userId}`)
  return res.json()
}

async function getPosts(userId: string) {
  const res = await fetch(`/api/users/${userId}/posts`)
  return res.json()
}

export default async function Dashboard({
  params,
}: {
  params: { userId: string }
}) {
  // Fetch in parallel
  const [user, posts] = await Promise.all([
    getUser(params.userId),
    getPosts(params.userId),
  ])

  return (
    <div>
      <h1>{user.name}</h1>
      <ul>
        {posts.map((post: Post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  )
}

Using Suspense for Streaming

// app/dashboard/page.tsx
import { Suspense } from "react"

async function UserInfo({ userId }: { userId: string }) {
  const user = await getUser(userId)
  return <h1>{user.name}</h1>
}

async function UserPosts({ userId }: { userId: string }) {
  const posts = await getPosts(userId)
  return (
    <ul>
      {posts.map((post: Post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

export default function Dashboard({
  params,
}: {
  params: { userId: string }
}) {
  return (
    <div>
      <Suspense fallback={<div>Loading user...</div>}>
        <UserInfo userId={params.userId} />
      </Suspense>
      <Suspense fallback={<div>Loading posts...</div>}>
        <UserPosts userId={params.userId} />
      </Suspense>
    </div>
  )
}

---

Sequential Data Fetching

When data depends on previous results:

// app/artist/[id]/page.tsx
async function getArtist(id: string) {
  const res = await fetch(`/api/artists/${id}`)
  return res.json()
}

async function getAlbums(artistId: string) {
  const res = await fetch(`/api/artists/${artistId}/albums`)
  return res.json()
}

export default async function ArtistPage({
  params,
}: {
  params: { id: string }
}) {
  // Sequential: albums depend on artist
  const artist = await getArtist(params.id)
  const albums = await getAlbums(artist.id)

  return (
    <div>
      <h1>{artist.name}</h1>
      <ul>
        {albums.map((album: Album) => (
          <li key={album.id}>{album.title}</li>
        ))}
      </ul>
    </div>
  )
}

---

Preloading Data

// lib/data.ts
import { cache } from "react"

export const getUser = cache(async (id: string) => {
  const res = await fetch(`/api/users/${id}`)
  return res.json()
})

export const preloadUser = (id: string) => {
  void getUser(id)
}

// app/user/[id]/page.tsx
import { getUser, preloadUser } from "@/lib/data"

export default async function UserPage({
  params,
}: {
  params: { id: string }
}) {
  // Start loading early
  preloadUser(params.id)

  // ... other work

  const user = await getUser(params.id)
  return <div>{user.name}</div>
}

---

Static Generation

generateStaticParams

// app/posts/[id]/page.tsx
export async function generateStaticParams() {
  const posts = await fetch("https://api.example.com/posts").then((res) =>
    res.json()
  )

  return posts.map((post: Post) => ({
    id: post.id.toString(),
  }))
}

export default async function PostPage({
  params,
}: {
  params: { id: string }
}) {
  const post = await getPost(params.id)
  return <article>{post.content}</article>
}

Generating Multiple Params

// app/[lang]/[slug]/page.tsx
export async function generateStaticParams() {
  const products = await getProducts()

  return products.flatMap((product) =>
    ["en", "es", "fr"].map((lang) => ({
      lang,
      slug: product.slug,
    }))
  )
}

---

Request Memoization

React automatically memoizes fetch requests with the same URL and options:

// This fetch is called in multiple components
async function getItem(id: string) {
  // Only one request is made even if called multiple times
  const res = await fetch(`/api/items/${id}`)
  return res.json()
}

// Component A
async function ComponentA({ id }: { id: string }) {
  const item = await getItem(id) // Request 1
  return <div>{item.name}</div>
}

// Component B
async function ComponentB({ id }: { id: string }) {
  const item = await getItem(id) // Deduplicated, uses cached result
  return <div>{item.description}</div>
}

---

Error Handling

Try-Catch Pattern

async function getData() {
  try {
    const res = await fetch("https://api.example.com/data")

    if (!res.ok) {
      throw new Error(`HTTP error! status: ${res.status}`)
    }

    return res.json()
  } catch (error) {
    console.error("Fetch error:", error)
    throw error // Re-throw to trigger error boundary
  }
}

With Error Boundary

// app/posts/error.tsx
"use client"

export default function Error({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  return (
    <div>
      <h2>Failed to load posts</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>Retry</button>
    </div>
  )
}

---

Last Updated: January 2026

Next.js Performance Optimization

Overview

Next.js provides built-in performance optimizations. This guide covers best practices for maximizing application performance.

---

Image Optimization

Using next/image

import Image from "next/image"

export function Hero() {
  return (
    <Image
      src="/hero.jpg"
      alt="Hero image"
      width={1200}
      height={600}
      priority // Load immediately for LCP
    />
  )
}

Responsive Images

<Image
  src="/photo.jpg"
  alt="Photo"
  fill
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
  className="object-cover"
/>

Remote Images

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "cdn.example.com",
        pathname: "/images/**",
      },
    ],
  },
}

Image Props Reference

---

Font Optimization

Using next/font

// app/layout.tsx
import { Inter, Roboto_Mono } from "next/font/google"

const inter = Inter({
  subsets: ["latin"],
  display: "swap",
  variable: "--font-inter",
})

const robotoMono = Roboto_Mono({
  subsets: ["latin"],
  display: "swap",
  variable: "--font-roboto-mono",
})

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
      <body>{children}</body>
    </html>
  )
}

Local Fonts

import localFont from "next/font/local"

const myFont = localFont({
  src: "./my-font.woff2",
  display: "swap",
})

export default function Layout({ children }) {
  return (
    <html className={myFont.className}>
      <body>{children}</body>
    </html>
  )
}

---

Script Optimization

Using next/script

import Script from "next/script"

export default function Page() {
  return (
    <>
      {/* Load after page is interactive */}
      <Script
        src="https://analytics.example.com/script.js"
        strategy="afterInteractive"
      />

      {/* Load during browser idle time */}
      <Script
        src="https://widget.example.com/script.js"
        strategy="lazyOnload"
      />

      {/* Block page load (rarely needed) */}
      <Script
        src="https://critical.example.com/script.js"
        strategy="beforeInteractive"
      />
    </>
  )
}

Script Strategies

---

Caching Strategies

Static Data (Default)

// Cached indefinitely
async function getData() {
  const res = await fetch("https://api.example.com/data")
  return res.json()
}

Time-Based Revalidation

// Revalidate every hour
async function getData() {
  const res = await fetch("https://api.example.com/data", {
    next: { revalidate: 3600 },
  })
  return res.json()
}

On-Demand Revalidation

// app/api/revalidate/route.ts
import { revalidateTag, revalidatePath } from "next/cache"

export async function POST(request: Request) {
  const { tag, path } = await request.json()

  if (tag) {
    revalidateTag(tag)
  } else if (path) {
    revalidatePath(path)
  }

  return Response.json({ revalidated: true })
}

Route Segment Config

// Force dynamic rendering
export const dynamic = "force-dynamic"

// Force static rendering
export const dynamic = "force-static"

// Set revalidation time
export const revalidate = 3600

---

Bundle Optimization

Dynamic Imports

import dynamic from "next/dynamic"

// Load component only when needed
const HeavyChart = dynamic(() => import("./heavy-chart"), {
  loading: () => <div>Loading chart...</div>,
  ssr: false, // Disable SSR for client-only components
})

export default function Dashboard() {
  return <HeavyChart />
}

Named Exports

const Chart = dynamic(
  () => import("./charts").then((mod) => mod.LineChart),
  { loading: () => <p>Loading...</p> }
)

Code Splitting by Route

Routes are automatically code-split. Each page only loads its dependencies.

---

Streaming and Suspense

Loading UI

// app/dashboard/loading.tsx
export default function Loading() {
  return <DashboardSkeleton />
}

Granular Suspense

import { Suspense } from "react"

export default function Page() {
  return (
    <div>
      <h1>Dashboard</h1>

      <Suspense fallback={<StatsSkeleton />}>
        <Stats />
      </Suspense>

      <Suspense fallback={<ChartSkeleton />}>
        <Chart />
      </Suspense>

      <Suspense fallback={<TableSkeleton />}>
        <DataTable />
      </Suspense>
    </div>
  )
}

---

Server Components

Benefits

• Zero JavaScript sent to client
• Direct backend access
• Improved initial load time
• Better SEO

Best Practices

// GOOD: Server Component (default)
export default async function PostList() {
  const posts = await db.post.findMany()
  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
}

// Only use "use client" when needed
"use client"
export function InteractiveButton() {
  const [clicked, setClicked] = useState(false)
  return <button onClick={() => setClicked(true)}>Click</button>
}

---

Prefetching

Automatic Prefetching

Links in viewport are automatically prefetched:

import Link from "next/link"

// Prefetched automatically when visible
<Link href="/about">About</Link>

// Disable prefetching
<Link href="/heavy-page" prefetch={false}>Heavy Page</Link>

Manual Prefetching

"use client"

import { useRouter } from "next/navigation"

export function PrefetchButton() {
  const router = useRouter()

  return (
    <button
      onMouseEnter={() => router.prefetch("/dashboard")}
      onClick={() => router.push("/dashboard")}
    >
      Go to Dashboard
    </button>
  )
}

---

Metadata Optimization

Static Metadata

export const metadata = {
  title: "My Site",
  description: "Welcome to my site",
  openGraph: {
    title: "My Site",
    description: "Welcome to my site",
    images: ["/og-image.jpg"],
  },
}

Dynamic Metadata

export async function generateMetadata({ params }) {
  const post = await getPost(params.id)

  return {
    title: post.title,
    description: post.excerpt,
  }
}

---

Build Optimization

Analyze Bundle

# Install analyzer
npm install @next/bundle-analyzer

# next.config.js
const withBundleAnalyzer = require("@next/bundle-analyzer")({
  enabled: process.env.ANALYZE === "true",
})

module.exports = withBundleAnalyzer({})

# Run analysis
ANALYZE=true npm run build

Optimize Dependencies

// next.config.js
module.exports = {
  // Reduce moment.js bundle size
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      "moment/locale": false,
    }
    return config
  },
}

---

Performance Checklist

Images

• [ ] Use next/image for all images
• [ ] Add priority to LCP image
• [ ] Provide sizes for responsive images
• [ ] Use appropriate quality settings

Fonts

• [ ] Use next/font for all fonts
• [ ] Specify display: swap
• [ ] Subset fonts to needed characters

JavaScript

• [ ] Use Server Components by default
• [ ] Dynamic import heavy components
• [ ] Analyze bundle size regularly

Data Fetching

• [ ] Implement appropriate caching
• [ ] Use parallel data fetching
• [ ] Stream content with Suspense

Core Web Vitals

• [ ] Optimize LCP (largest contentful paint)
• [ ] Minimize CLS (cumulative layout shift)
• [ ] Reduce FID/INP (interaction delay)

---

Last Updated: January 2026

Next.js Routing Reference

File-Based Routing

Next.js App Router uses a file-system based router where:

• Folders define routes
• Files define UI

---

Basic Routes

Static Routes

app/
├── page.tsx          # /
├── about/
│   └── page.tsx      # /about
└── blog/
    └── page.tsx      # /blog

Nested Routes

app/
└── blog/
    ├── page.tsx           # /blog
    └── posts/
        └── page.tsx       # /blog/posts

---

Dynamic Routes

Single Parameter

app/
└── posts/
    └── [id]/
        └── page.tsx       # /posts/1, /posts/2, etc.

// app/posts/[id]/page.tsx
export default function PostPage({
  params,
}: {
  params: { id: string }
}) {
  return <div>Post: {params.id}</div>
}

Multiple Parameters

app/
└── shop/
    └── [category]/
        └── [product]/
            └── page.tsx   # /shop/electronics/phone

// app/shop/[category]/[product]/page.tsx
export default function ProductPage({
  params,
}: {
  params: { category: string; product: string }
}) {
  return (
    <div>
      Category: {params.category}
      Product: {params.product}
    </div>
  )
}

Catch-All Segments

app/
└── docs/
    └── [...slug]/
        └── page.tsx       # /docs/a, /docs/a/b, /docs/a/b/c

// app/docs/[...slug]/page.tsx
export default function DocsPage({
  params,
}: {
  params: { slug: string[] }
}) {
  // /docs/a/b/c -> slug = ['a', 'b', 'c']
  return <div>Path: {params.slug.join("/")}</div>
}

Optional Catch-All

app/
└── docs/
    └── [[...slug]]/
        └── page.tsx       # /docs, /docs/a, /docs/a/b

---

Route Groups

Groups organize routes without affecting the URL.

Syntax: (folderName)

app/
├── (marketing)/
│   ├── about/page.tsx     # /about
│   └── contact/page.tsx   # /contact
├── (shop)/
│   ├── products/page.tsx  # /products
│   └── cart/page.tsx      # /cart
└── page.tsx               # /

Multiple Layouts

app/
├── (marketing)/
│   ├── layout.tsx         # Marketing layout
│   ├── about/page.tsx
│   └── blog/page.tsx
├── (app)/
│   ├── layout.tsx         # App layout (authenticated)
│   ├── dashboard/page.tsx
│   └── settings/page.tsx
└── layout.tsx             # Root layout

---

Parallel Routes

Render multiple pages simultaneously in the same layout.

Syntax: @folderName

app/
├── @dashboard/
│   └── page.tsx
├── @analytics/
│   └── page.tsx
├── layout.tsx
└── page.tsx

// app/layout.tsx
export default function Layout({
  children,
  dashboard,
  analytics,
}: {
  children: React.ReactNode
  dashboard: React.ReactNode
  analytics: React.ReactNode
}) {
  return (
    <div>
      {children}
      <div className="panels">
        {dashboard}
        {analytics}
      </div>
    </div>
  )
}

Default Files

app/
├── @team/
│   ├── page.tsx           # Shown at /
│   └── settings/page.tsx  # Shown at /settings
├── @analytics/
│   ├── page.tsx
│   └── default.tsx        # Fallback when no match
└── layout.tsx

---

Intercepting Routes

Load a route within the current layout (modal patterns).

Convention

Modal Example

app/
├── @modal/
│   └── (.)photo/
│       └── [id]/
│           └── page.tsx   # Modal view
├── photo/
│   └── [id]/
│       └── page.tsx       # Full page view
├── layout.tsx
└── page.tsx

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

---

Navigation

Link Component

import Link from "next/link"

export function Navigation() {
  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
      <Link href="/posts/1">Post 1</Link>
      <Link href={{ pathname: "/posts", query: { sort: "asc" } }}>
        Posts (sorted)
      </Link>
    </nav>
  )
}

Programmatic Navigation

"use client"

import { useRouter } from "next/navigation"

export function LoginButton() {
  const router = useRouter()

  function handleLogin() {
    // ... authenticate
    router.push("/dashboard")
  }

  return <button onClick={handleLogin}>Login</button>
}

Router Methods

const router = useRouter()

router.push("/dashboard")        // Navigate to route
router.replace("/login")         // Replace current history entry
router.refresh()                 // Refresh current route
router.prefetch("/about")        // Prefetch route
router.back()                    // Go back
router.forward()                 // Go forward

---

Route Handlers (API Routes)

Basic Handler

// app/api/posts/route.ts
import { NextResponse } from "next/server"

export async function GET() {
  const posts = await getPosts()
  return NextResponse.json(posts)
}

export async function POST(request: Request) {
  const body = await request.json()
  const post = await createPost(body)
  return NextResponse.json(post, { status: 201 })
}

Dynamic Route Handler

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

export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const post = await getPost(params.id)

  if (!post) {
    return NextResponse.json(
      { error: "Post not found" },
      { status: 404 }
    )
  }

  return NextResponse.json(post)
}

---

Hooks

usePathname

"use client"

import { usePathname } from "next/navigation"

export function NavLink({ href, children }) {
  const pathname = usePathname()
  const isActive = pathname === href

  return (
    <a href={href} className={isActive ? "active" : ""}>
      {children}
    </a>
  )
}

useSearchParams

"use client"

import { useSearchParams } from "next/navigation"

export function SearchResults() {
  const searchParams = useSearchParams()
  const query = searchParams.get("q")

  return <div>Searching for: {query}</div>
}

useParams

"use client"

import { useParams } from "next/navigation"

export function PostInfo() {
  const params = useParams()
  // For /posts/[id] -> params.id
  return <div>Post ID: {params.id}</div>
}

useSelectedLayoutSegment

"use client"

import { useSelectedLayoutSegment } from "next/navigation"

export function NavTabs() {
  const segment = useSelectedLayoutSegment()
  // Returns the active child segment

  return (
    <nav>
      <a className={segment === "posts" ? "active" : ""}>Posts</a>
      <a className={segment === "users" ? "active" : ""}>Users</a>
    </nav>
  )
}

---

Redirects

In Server Components

import { redirect } from "next/navigation"

export default async function Page() {
  const user = await getUser()

  if (!user) {
    redirect("/login")
  }

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

In Route Handlers

import { redirect } from "next/navigation"

export async function GET(request: Request) {
  const session = await getSession()

  if (!session) {
    redirect("/login")
  }

  // ...
}

Permanent Redirect

import { permanentRedirect } from "next/navigation"

export default function Page() {
  permanentRedirect("/new-location")
}

---

Middleware

// middleware.ts (at project root)
import { NextResponse } from "next/server"
import type { NextRequest } from "next/server"

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

  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
    return NextResponse.redirect(new URL("/login", request.url))
  }

  return NextResponse.next()
}

export const config = {
  matcher: ["/dashboard/:path*", "/api/:path*"],
}

---

Last Updated: January 2026

Server Components vs Client Components

Overview

Next.js App Router uses React Server Components by default. Understanding when to use Server vs Client Components is crucial for building performant applications.

---

Server Components (Default)

Server Components render on the server and send HTML to the client.

Benefits

• Zero JavaScript: No JS bundle sent to client for the component
• Direct backend access: Query databases, access file system
• Improved security: Keep sensitive data on server
• Caching: Results can be cached and reused
• Better SEO: Full HTML available for crawlers

Capabilities

• Fetch data directly
• Access backend resources
• Keep sensitive information server-side
• Import large dependencies without client impact

Limitations

• Cannot use hooks (useState, useEffect)
• Cannot use browser APIs
• Cannot add event handlers (onClick, onChange)
• Cannot use Context providers

Example

// app/posts/page.tsx (Server Component by default)
import { db } from "@/lib/db"

export default async function PostsPage() {
  // Direct database access
  const posts = await db.post.findMany({
    include: { author: true },
  })

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <h2>{post.title}</h2>
          <p>By {post.author.name}</p>
        </li>
      ))}
    </ul>
  )
}

---

Client Components

Client Components are pre-rendered on the server and hydrated on the client for interactivity.

When to Use

• Interactivity: onClick, onChange handlers
• State: useState, useReducer
• Effects: useEffect, useLayoutEffect
• Browser APIs: window, document, localStorage
• Custom hooks: Hooks that depend on state/effects
• React Class components: If using legacy patterns

Declaration

"use client" // Add at the top of the file

import { useState } from "react"

export function Counter() {
  const [count, setCount] = useState(0)

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  )
}

---

Composition Patterns

Pattern 1: Server Component with Client Children

// app/dashboard/page.tsx (Server Component)
import { db } from "@/lib/db"
import { InteractiveChart } from "./chart"

export default async function Dashboard() {
  const data = await db.analytics.findMany()

  return (
    <div>
      <h1>Dashboard</h1>
      {/* Pass server data to client component */}
      <InteractiveChart data={data} />
    </div>
  )
}

// app/dashboard/chart.tsx (Client Component)
"use client"

import { useState } from "react"

export function InteractiveChart({ data }: { data: DataPoint[] }) {
  const [selectedRange, setSelectedRange] = useState("week")

  return (
    <div>
      <select
        value={selectedRange}
        onChange={(e) => setSelectedRange(e.target.value)}
      >
        <option value="day">Day</option>
        <option value="week">Week</option>
        <option value="month">Month</option>
      </select>
      {/* Render chart with data */}
    </div>
  )
}

Pattern 2: Client Component Wrapping Server Children

// app/page.tsx (Server Component)
import { Modal } from "@/components/modal"
import { ServerContent } from "./server-content"

export default function Page() {
  return (
    <Modal>
      {/* Server Component passed as children */}
      <ServerContent />
    </Modal>
  )
}

// components/modal.tsx (Client Component)
"use client"

import { useState } from "react"

export function Modal({ children }: { children: React.ReactNode }) {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open</button>
      {isOpen && (
        <div className="modal">
          {children}
          <button onClick={() => setIsOpen(false)}>Close</button>
        </div>
      )}
    </>
  )
}

---

Decision Guide

---

Common Patterns

Passing Server Data to Client Components

// Server Component
export default async function Page() {
  const user = await getUser()

  // Serialize and pass to client
  return <UserProfile user={user} />
}

// Client Component
"use client"

export function UserProfile({ user }: { user: User }) {
  const [isEditing, setIsEditing] = useState(false)
  // user data is already fetched, just handle UI state
}

Moving Client Components Down

// BAD: Entire page is client component
"use client"

export default function Page() {
  const [search, setSearch] = useState("")
  const posts = usePosts() // Client-side fetching

  return (
    <div>
      <input value={search} onChange={(e) => setSearch(e.target.value)} />
      <PostList posts={posts} />
    </div>
  )
}

// GOOD: Only SearchBar is client component
// app/posts/page.tsx (Server Component)
export default async function Page() {
  const posts = await getPosts() // Server-side fetching

  return (
    <div>
      <SearchBar /> {/* Client component */}
      <PostList posts={posts} /> {/* Server component */}
    </div>
  )
}

// app/posts/search-bar.tsx
"use client"

export function SearchBar() {
  const [search, setSearch] = useState("")
  // Handle search with URL params or server action
}

Context Providers

// app/providers.tsx
"use client"

import { ThemeProvider } from "next-themes"

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system">
      {children}
    </ThemeProvider>
  )
}

// app/layout.tsx (Server Component)
import { Providers } from "./providers"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

---

Third-Party Libraries

Many third-party components need "use client" because they use hooks.

Wrapping Client-Only Libraries

// components/carousel.tsx
"use client"

import { Carousel as LibCarousel } from "some-carousel-lib"

export function Carousel(props: CarouselProps) {
  return <LibCarousel {...props} />
}

Using in Server Components

// app/page.tsx (Server Component)
import { Carousel } from "@/components/carousel"

export default async function Page() {
  const images = await getImages()

  return (
    <div>
      <h1>Gallery</h1>
      <Carousel images={images} />
    </div>
  )
}

---

Serialization Rules

When passing props from Server to Client Components, data must be serializable:

Supported Types

• Primitives (string, number, boolean, null, undefined)
• Arrays and objects containing serializable values
• Date (serialized to string)
• Map, Set (serialized)
• TypedArrays, ArrayBuffer

Not Supported

• Functions
• Classes (instances)
• Symbols
• React elements (except as children)

// This works
<ClientComponent
  data={{ name: "John", count: 42 }}
  items={["a", "b", "c"]}
  date={new Date()}
/>

// This does NOT work
<ClientComponent
  onClick={() => console.log("clicked")} // Function
  user={new User("John")} // Class instance
/>

---

Last Updated: January 2026

Next.js Testing Patterns

Overview

This guide covers testing strategies for Next.js applications using Jest, React Testing Library, and Playwright.

---

Setup

Jest Configuration

// jest.config.js
const nextJest = require("next/jest")

const createJestConfig = nextJest({
  dir: "./",
})

const customJestConfig = {
  setupFilesAfterEnv: ["<rootDir>/jest.setup.js"],
  testEnvironment: "jest-environment-jsdom",
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
  },
}

module.exports = createJestConfig(customJestConfig)

Jest Setup

// jest.setup.js
import "@testing-library/jest-dom"

Package Installation

npm install --save-dev jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom

---

Component Testing

Basic Component Test

// components/button.test.tsx
import { render, screen, fireEvent } from "@testing-library/react"
import { Button } from "./button"

describe("Button", () => {
  it("renders button with text", () => {
    render(<Button>Click me</Button>)

    expect(screen.getByRole("button")).toHaveTextContent("Click me")
  })

  it("calls onClick when clicked", () => {
    const handleClick = jest.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()
  })
})

Testing with User Events

import { render, screen } from "@testing-library/react"
import userEvent from "@testing-library/user-event"
import { SearchInput } from "./search-input"

describe("SearchInput", () => {
  it("updates value on user input", async () => {
    const user = userEvent.setup()
    const handleSearch = jest.fn()

    render(<SearchInput onSearch={handleSearch} />)

    const input = screen.getByRole("textbox")
    await user.type(input, "hello")

    expect(input).toHaveValue("hello")
  })

  it("submits on enter key", async () => {
    const user = userEvent.setup()
    const handleSearch = jest.fn()

    render(<SearchInput onSearch={handleSearch} />)

    await user.type(screen.getByRole("textbox"), "test{enter}")

    expect(handleSearch).toHaveBeenCalledWith("test")
  })
})

---

Testing Async Components

Server Component Testing

// app/posts/page.test.tsx
import { render, screen } from "@testing-library/react"
import PostsPage from "./page"

// Mock the data fetching
jest.mock("@/lib/db", () => ({
  db: {
    post: {
      findMany: jest.fn().mockResolvedValue([
        { id: "1", title: "Post 1" },
        { id: "2", title: "Post 2" },
      ]),
    },
  },
}))

describe("PostsPage", () => {
  it("renders posts from database", async () => {
    const PostsPageComponent = await PostsPage()
    render(PostsPageComponent)

    expect(screen.getByText("Post 1")).toBeInTheDocument()
    expect(screen.getByText("Post 2")).toBeInTheDocument()
  })
})

Testing with Suspense

import { render, screen, waitFor } from "@testing-library/react"
import { Suspense } from "react"
import { PostList } from "./post-list"

describe("PostList", () => {
  it("shows loading state then content", async () => {
    render(
      <Suspense fallback={<div>Loading...</div>}>
        <PostList />
      </Suspense>
    )

    expect(screen.getByText("Loading...")).toBeInTheDocument()

    await waitFor(() => {
      expect(screen.getByText("Post 1")).toBeInTheDocument()
    })
  })
})

---

Testing Hooks

Custom Hook Testing

// hooks/use-counter.test.ts
import { renderHook, act } from "@testing-library/react"
import { useCounter } from "./use-counter"

describe("useCounter", () => {
  it("initializes with default value", () => {
    const { result } = renderHook(() => useCounter())

    expect(result.current.count).toBe(0)
  })

  it("initializes with custom value", () => {
    const { result } = renderHook(() => useCounter(10))

    expect(result.current.count).toBe(10)
  })

  it("increments count", () => {
    const { result } = renderHook(() => useCounter())

    act(() => {
      result.current.increment()
    })

    expect(result.current.count).toBe(1)
  })

  it("decrements count", () => {
    const { result } = renderHook(() => useCounter(5))

    act(() => {
      result.current.decrement()
    })

    expect(result.current.count).toBe(4)
  })
})

---

API Route Testing

Route Handler Testing

// app/api/posts/route.test.ts
import { GET, POST } from "./route"
import { NextRequest } from "next/server"

// Mock the database
jest.mock("@/lib/db", () => ({
  db: {
    post: {
      findMany: jest.fn(),
      create: jest.fn(),
    },
  },
}))

import { db } from "@/lib/db"

describe("POST /api/posts", () => {
  beforeEach(() => {
    jest.clearAllMocks()
  })

  it("returns all posts", async () => {
    const mockPosts = [
      { id: "1", title: "Post 1" },
      { id: "2", title: "Post 2" },
    ]
    ;(db.post.findMany as jest.Mock).mockResolvedValue(mockPosts)

    const response = await GET()
    const data = await response.json()

    expect(response.status).toBe(200)
    expect(data).toEqual(mockPosts)
  })

  it("creates a new post", async () => {
    const newPost = { id: "3", title: "New Post" }
    ;(db.post.create as jest.Mock).mockResolvedValue(newPost)

    const request = new NextRequest("http://localhost/api/posts", {
      method: "POST",
      body: JSON.stringify({ title: "New Post" }),
    })

    const response = await POST(request)
    const data = await response.json()

    expect(response.status).toBe(201)
    expect(data).toEqual(newPost)
  })
})

---

Server Actions Testing

Testing Server Actions

// app/actions.test.ts
import { createPost, deletePost } from "./actions"
import { revalidatePath } from "next/cache"

jest.mock("next/cache", () => ({
  revalidatePath: jest.fn(),
}))

jest.mock("@/lib/db", () => ({
  db: {
    post: {
      create: jest.fn(),
      delete: jest.fn(),
    },
  },
}))

import { db } from "@/lib/db"

describe("Server Actions", () => {
  beforeEach(() => {
    jest.clearAllMocks()
  })

  describe("createPost", () => {
    it("creates post and revalidates path", async () => {
      const formData = new FormData()
      formData.append("title", "Test Post")
      formData.append("content", "Test content")

      ;(db.post.create as jest.Mock).mockResolvedValue({
        id: "1",
        title: "Test Post",
      })

      await createPost(formData)

      expect(db.post.create).toHaveBeenCalledWith({
        data: {
          title: "Test Post",
          content: "Test content",
        },
      })
      expect(revalidatePath).toHaveBeenCalledWith("/posts")
    })
  })

  describe("deletePost", () => {
    it("deletes post by id", async () => {
      await deletePost("1")

      expect(db.post.delete).toHaveBeenCalledWith({
        where: { id: "1" },
      })
    })
  })
})

---

Integration Testing

Testing Page with Router

// app/posts/[id]/page.test.tsx
import { render, screen } from "@testing-library/react"
import PostPage from "./page"

jest.mock("next/navigation", () => ({
  useRouter: () => ({
    push: jest.fn(),
    back: jest.fn(),
  }),
  useParams: () => ({ id: "1" }),
}))

jest.mock("@/lib/api", () => ({
  getPost: jest.fn().mockResolvedValue({
    id: "1",
    title: "Test Post",
    content: "Test content",
  }),
}))

describe("PostPage", () => {
  it("renders post content", async () => {
    const PageComponent = await PostPage({ params: { id: "1" } })
    render(PageComponent)

    expect(screen.getByText("Test Post")).toBeInTheDocument()
    expect(screen.getByText("Test content")).toBeInTheDocument()
  })
})

---

E2E Testing with Playwright

Setup

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: "html",
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
  },
  projects: [
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"] },
    },
  ],
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
})

E2E Tests

// e2e/posts.spec.ts
import { test, expect } from "@playwright/test"

test.describe("Posts", () => {
  test("displays posts list", async ({ page }) => {
    await page.goto("/posts")

    await expect(page.getByRole("heading", { name: "Posts" })).toBeVisible()
    await expect(page.getByRole("listitem")).toHaveCount(3)
  })

  test("creates new post", async ({ page }) => {
    await page.goto("/posts/new")

    await page.getByLabel("Title").fill("New Post")
    await page.getByLabel("Content").fill("Post content")
    await page.getByRole("button", { name: "Create" }).click()

    await expect(page).toHaveURL(/\/posts\/\d+/)
    await expect(page.getByText("New Post")).toBeVisible()
  })

  test("navigates to post detail", async ({ page }) => {
    await page.goto("/posts")

    await page.getByRole("link", { name: "First Post" }).click()

    await expect(page).toHaveURL("/posts/1")
    await expect(page.getByText("First Post")).toBeVisible()
  })
})

---

Mocking Patterns

Mocking Next.js Modules

// Mock next/navigation
jest.mock("next/navigation", () => ({
  useRouter: () => ({
    push: jest.fn(),
    replace: jest.fn(),
    back: jest.fn(),
    forward: jest.fn(),
    refresh: jest.fn(),
    prefetch: jest.fn(),
  }),
  usePathname: () => "/current-path",
  useSearchParams: () => new URLSearchParams("q=test"),
  useParams: () => ({ id: "1" }),
}))

// Mock next/headers
jest.mock("next/headers", () => ({
  cookies: () => ({
    get: jest.fn(),
    set: jest.fn(),
    delete: jest.fn(),
  }),
  headers: () => new Headers(),
}))

Mocking Fetch

// Global fetch mock
global.fetch = jest.fn(() =>
  Promise.resolve({
    ok: true,
    json: () => Promise.resolve({ data: "mocked" }),
  })
) as jest.Mock

// Per-test mock
beforeEach(() => {
  ;(fetch as jest.Mock).mockImplementation(() =>
    Promise.resolve({
      ok: true,
      json: () => Promise.resolve([]),
    })
  )
})

---

Testing Best Practices

Guidelines

• Test behavior, not implementation
• Use meaningful test descriptions
• Keep tests independent
• Mock external dependencies
• Test error states and edge cases

File Organization

src/
├── components/
│   ├── button.tsx
│   └── button.test.tsx
├── app/
│   └── posts/
│       ├── page.tsx
│       └── page.test.tsx
└── e2e/
    └── posts.spec.ts

Running Tests

# Unit tests
npm test

# Watch mode
npm test -- --watch

# Coverage
npm test -- --coverage

# E2E tests
npx playwright test

---

Last Updated: January 2026