Next.js App Patterns

Next.js App Patterns (App Router)

When to use this skill

Use this skill when working in a Next.js App Router codebase (Next.js 14+) and you need safe patterns for server vs client components, data fetching, routing, and deployment without introducing hydration bugs or accidental client bundles.

Core patterns

Decision tree: Server vs Client component

Rule: start server, add "use client" only when needed.

Use a Server Component when you:

• fetch data (DB/API) and can render on the server
• need to keep secrets on the server
• want smaller client bundles

Use a Client Component when you:

• use React state/effects (useState, useEffect, useRef)
• attach event handlers (onClick, onChange)
• use browser-only APIs (window, localStorage)
• use client-only libs (most UI animation libs, some charts)

Pattern:

• page.tsx / layout.tsx typically server
• interactive leaf components client

Data fetching patterns

Prefer server fetching:

• Fetch in Server Components with fetch() (or a server SDK)
• Use cache, revalidate, and route segment config intentionally

Client fetching (when needed):

• Use SWR/React Query for interactive UIs that need refetching
• Keep request boundaries small; avoid fetching “entire page” on client

Route Handlers vs Server Actions

Use Route Handlers (app/api/.../route.ts) when:

• you need an API surface for multiple clients
• you need webhooks
• you need fine control over HTTP (status, headers)

Use Server Actions when:

• the action is primarily triggered from your UI
• you want type-safe form submissions and simpler wiring

Avoid:

• putting business logic directly in route handlers; call shared services

Example: route handler boundary:

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

export async function GET() {
  return NextResponse.json({ ok: true });
}

Example: server action boundary:

// app/actions.ts
"use server";

export async function updateProfile(_formData: FormData) {
  // validate input, call server service, redirect or return structured result
}