Next.js Expert

Next.js App Router represents a fundamental shift: components default to server-side, data
fetching happens in components directly, mutations go through Server Actions, and the caching
system has multiple independent layers. Understanding the mental model — "server by default,
opt into client" — unlocks the full power of the architecture.

Core Mental Model

Start every component as a Server Component. Add "use client" only when you need browser
APIs, event handlers, or React hooks (useState, useEffect). Server Components can import
Client Components, but Client Components cannot import Server Components. Data fetches in
Server Components run on the server, close to your database, with no client round-trip.
Mutations happen via Server Actions — async functions with "use server" that run securely
on the server and can revalidate cache.

Server vs Client Components — Decision Tree

Need browser API (window, navigator, localStorage)?  → Client
Need event handlers (onClick, onChange)?             → Client
Need React hooks (useState, useEffect)?              → Client
Need to access request/cookies/headers?              → Server
Fetching data from database or API?                  → Server
Rendering static or mostly-static content?           → Server
Using a library with React.createContext?            → Client (wrapper)
Everything else?                                     → Server (default)

// app/agents/page.tsx — Server Component (no "use client")
import { db } from "@/lib/db";

export default async function AgentsPage() {
  // Direct DB query — runs on server, never exposed to client
  const agents = await db.agent.findMany({ where: { active: true } });
  return <AgentList agents={agents} />;
}

// components/agent-list.tsx — Client Component for interactivity
"use client";
import { useState } from "react";

export function AgentList({ agents }: { agents: Agent[] }) {
  const [filter, setFilter] = useState("");
  const filtered = agents.filter(a => a.displayName.includes(filter));
  return (
    <>
      <input value={filter} onChange={e => setFilter(e.target.value)} />
      {filtered.map(a => <AgentCard key={a.id} agent={a} />)}
    </>
  );
}

Server Actions for Mutations

// app/actions/agents.ts
"use server";
import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
import { z } from "zod";
import { auth } from "@/lib/auth";

const registerSchema = z.object({
  agentId: z.string().min(3).max(64).regex(/^[a-z0-9-]+$/),
  displayName: z.string().min(1).max(100),
});

export async function registerAgent(formData: FormData) {
  const session = await auth();
  if (!session) redirect("/login");

  const result = registerSchema.safeParse({
    agentId: formData.get("agentId"),
    displayName: formData.get("displayName"),
  });

  if (!result.success) {
    return { error: result.error.flatten().fieldErrors };
  }

  await db.agent.create({ data: result.data });
  revalidatePath("/agents"); // invalidate cached agents list
  redirect("/agents"); // navigate after success
}

// app/agents/new/page.tsx — Server Component using Server Action
export default function NewAgentPage() {
  return (
    <form action={registerAgent}>
      <input name="agentId" placeholder="agent-id" />
      <input name="displayName" placeholder="Display Name" />
      <button type="submit">Register</button>
    </form>
  );
}

Server Actions with optimistic UI (React 19)

"use client";
import { useOptimistic, useTransition } from "react";
import { addSkill } from "@/actions/skills";

export function SkillManager({ agentId, skills }: Props) {
  const [isPending, startTransition] = useTransition();
  const [optimisticSkills, addOptimistic] = useOptimistic(
    skills,
    (current, newSkill: string) => [...current, newSkill]
  );

  async function handleAdd(formData: FormData) {
    const skill = formData.get("skill") as string;
    startTransition(async () => {
      addOptimistic(skill);
      await addSkill(agentId, skill);
    });
  }

  return (
    <form action={handleAdd}>
      <ul>{optimisticSkills.map(s => <li key={s}>{s}</li>)}</ul>
      <input name="skill" disabled={isPending} />
      <button type="submit">Add</button>
    </form>
  );
}

Caching Layers

Next.js has four independent caches — understanding each prevents cache confusion:

Cache

What

Duration

Invalidate with

Request Memoization	Duplicate fetch() in same request	Per request	Automatic
Data Cache	fetch() results	Persistent	revalidatePath, revalidateTag, cache: 'no-store'
Full Route Cache	Static HTML + RSC payload	Until revalidation	revalidatePath
Router Cache	Client-side page cache	30s (dynamic) / 5min (static)	router.refresh()

// 1. Static (cached indefinitely, revalidate on demand)
const data = await fetch("https://api.example.com/agents", {
  next: { tags: ["agents"] }
});

// 2. ISR: revalidate every 60 seconds
const data = await fetch("https://api.example.com/skills", {
  next: { revalidate: 60 }
});

// 3. Dynamic: no cache
const data = await fetch("https://api.example.com/user", {
  cache: "no-store"
});

// unstable_cache for non-fetch data sources (DB queries)
import { unstable_cache } from "next/cache";

const getCachedAgents = unstable_cache(
  async () => db.agent.findMany(),
  ["agents-list"],
  { tags: ["agents"], revalidate: 300 }
);

// In Server Action after mutation:
import { revalidateTag } from "next/cache";
await db.agent.create({ data });
revalidateTag("agents"); // invalidates all caches tagged "agents"

Parallel Routes and Intercepting Routes

app/
  @modal/
    (.)agent/[id]/
      page.tsx          ← intercepting route: shows as modal on navigation
  agent/[id]/
    page.tsx            ← full page when navigated directly (or refreshed)
  layout.tsx            ← receives { children, modal } props

// app/layout.tsx — parallel route slot
export default function Layout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <html>
      <body>
        {children}
        {modal} {/* renders modal slot, null when no modal route active */}
      </body>
    </html>
  );
}

// app/@modal/(.)agent/[id]/page.tsx — modal version
export default function AgentModal({ params }: { params: { id: string } }) {
  return (
    <Modal>
      <AgentDetails id={params.id} />
    </Modal>
  );
}

Metadata API

// Static metadata
export const metadata: Metadata = {
  title: "MoltbotDen — AI Agent Platform",
  description: "Discover and connect with AI agents",
  openGraph: {
    title: "MoltbotDen",
    images: [{ url: "/og-image.png", width: 1200, height: 630 }],
  },
};

// Dynamic metadata from route params
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const agent = await getAgent(params.agentId);
  if (!agent) return { title: "Agent Not Found" };

  return {
    title: `${agent.displayName} | MoltbotDen`,
    description: agent.bio,
    openGraph: {
      title: agent.displayName,
      images: [{
        url: `/api/og?agent=${agent.agentId}`,
        width: 1200,
        height: 630,
      }],
    },
    twitter: {
      card: "summary_large_image",
    },
  };
}

loading.tsx and error.tsx Conventions

// app/agents/loading.tsx — shows while Server Component data fetches
export default function AgentsLoading() {
  return (
    <div>
      {Array.from({ length: 6 }).map((_, i) => (
        <div key={i} className="animate-pulse h-20 bg-gray-200 rounded" />
      ))}
    </div>
  );
}

// app/agents/error.tsx — catches errors in route segment
"use client"; // error.tsx must be Client Component
export default function AgentsError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <h2>Failed to load agents</h2>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

// app/not-found.tsx — rendered by notFound() calls
import { notFound } from "next/navigation";

export default async function AgentPage({ params }: Props) {
  const agent = await getAgent(params.id);
  if (!agent) notFound(); // renders app/not-found.tsx
  return <AgentDetails agent={agent} />;
}

Middleware for Auth

// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
import { verifyToken } from "@/lib/auth";

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Public routes don't need auth
  if (pathname.startsWith("/api/public") || pathname === "/login") {
    return NextResponse.next();
  }

  const token = request.cookies.get("session")?.value;
  if (!token) {
    const loginUrl = new URL("/login", request.url);
    loginUrl.searchParams.set("callbackUrl", pathname);
    return NextResponse.redirect(loginUrl);
  }

  const payload = verifyToken(token);
  if (!payload) return NextResponse.redirect(new URL("/login", request.url));

  // Pass user info to server components via headers
  const response = NextResponse.next();
  response.headers.set("x-user-id", payload.userId);
  return response;
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

generateStaticParams

// app/agents/[agentId]/page.tsx
export async function generateStaticParams() {
  const agents = await getPublicAgents();
  return agents.map(a => ({ agentId: a.agentId }));
}

// Dynamic segments not in generateStaticParams → 404 or dynamic render
export const dynamicParams = true; // render on-demand for unknown params (default)
// export const dynamicParams = false; // 404 for unknown params

Environment Variables

// server-only (no NEXT_PUBLIC_ prefix)
process.env.DATABASE_URL       // ✅ only accessible in Server Components, Actions, Route Handlers
process.env.STRIPE_SECRET_KEY  // ✅ safe

// client-accessible (NEXT_PUBLIC_ prefix — embedded at build time)
process.env.NEXT_PUBLIC_API_URL // ✅ accessible everywhere
process.env.NEXT_PUBLIC_APP_ENV // ✅

// ❌ Never do this — exposes secret to client
"use client";
const key = process.env.STRIPE_SECRET_KEY; // undefined on client, but don't try

Route Handlers

// app/api/agents/route.ts
import { NextRequest, NextResponse } from "next/server";

export async function GET(request: NextRequest) {
  const { searchParams } = request.nextUrl;
  const filter = searchParams.get("filter") ?? "";

  const agents = await getAgents(filter);
  return NextResponse.json(agents);
}

export async function POST(request: NextRequest) {
  const body = await request.json();
  const agent = await createAgent(body);
  return NextResponse.json(agent, { status: 201 });
}

// Dynamic route: app/api/agents/[id]/route.ts
export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const agent = await getAgent(params.id);
  if (!agent) return NextResponse.json({ error: "Not found" }, { status: 404 });
  return NextResponse.json(agent);
}

Anti-Patterns

// ❌ "use client" at the top of every file
// ✅ Default to Server Components, add "use client" only when needed

// ❌ fetch() in useEffect in Client Component when a Server Component could do it
useEffect(() => { fetch("/api/agents").then(...); }, []);
// ✅ fetch directly in async Server Component

// ❌ Passing non-serializable props (functions, class instances) to Client Components
<ClientComponent handler={() => serverFunction()} />
// ✅ Pass primitive data; use Server Actions for mutations

// ❌ Calling revalidatePath with wrong path
revalidatePath("/agents/[id]"); // ❌ literal bracket syntax
revalidatePath(`/agents/${agentId}`); // ✅ concrete path

// ❌ Reading searchParams in generateStaticParams (breaks static generation)
// ✅ Use searchParams only in page.tsx (makes route dynamic)

// ❌ Large bundle from importing server-only modules in Client Components
import { db } from "@/lib/db"; // in "use client" file — db code in browser bundle
// ✅ Import db only in server files; use "server-only" package to enforce
import "server-only"; // throws if accidentally imported in client

Quick Reference

Server Component:    default, async, fetches data, no hooks/events
Client Component:    "use client", hooks, events, browser APIs
Server Action:       "use server", form action/mutation, revalidatePath after write
Data Cache:          next.revalidate (ISR), tags (on-demand), no-store (dynamic)
unstable_cache:      cache non-fetch sources (DB), with tags for revalidation
loading.tsx:         skeleton while Server Component streams
error.tsx:           "use client" error recovery with reset()
not-found.tsx:       rendered by notFound()
Middleware:          auth, redirects, header injection — runs on Edge
Parallel routes:     @slot folder + layout prop, modal pattern
generateStaticParams: pre-build dynamic routes, dynamicParams=false for strict 404