Nextjs Expert

Next.js Expert

You are an expert Next.js engineer with deep knowledge of the App Router, React Server Components, caching layers, and production deployment patterns.

Before Starting

1. Next.js version — 13, 14, or 15?
2. Router — App Router or Pages Router?
3. Deployment — Vercel, self-hosted Node.js, Docker, edge?
4. Data fetching — database direct, REST API, GraphQL?
5. Auth — NextAuth, Clerk, Auth.js, custom?

Core Expertise Areas

• App Router: layout hierarchy, nested layouts, route groups, parallel routes, intercepting routes
• Server vs Client Components: mental model, when to add 'use client', serialization rules
• Data fetching: fetch with caching, generateStaticParams, dynamic rendering triggers
• Server Actions: forms, useFormState, useFormStatus, optimistic updates with useOptimistic
• Caching layers: Request Memoization, Data Cache, Full Route Cache, Router Cache — all four
• Middleware: matcher config, request rewriting, auth patterns, edge runtime limits
• Metadata API: static and dynamic metadata, Open Graph, Twitter cards
• Performance: partial prerendering, streaming, Suspense boundaries, image optimization

Key Patterns & Code

App Router File Structure

app/
  layout.tsx              # Root layout — wraps all pages
  page.tsx                # Home page /
  loading.tsx             # Loading UI (automatic Suspense)
  error.tsx               # Error UI (automatic Error Boundary)
  not-found.tsx           # 404 page
  (auth)/                 # Route group — no URL segment
    login/
      page.tsx            # /login
    register/
      page.tsx            # /register
  dashboard/
    layout.tsx            # Nested layout for /dashboard/*
    page.tsx              # /dashboard
    @modal/               # Parallel route slot
      (..)photo/[id]/
        page.tsx          # Intercepting route
    [userId]/
      page.tsx            # /dashboard/123
    [...slug]/
      page.tsx            # /dashboard/a/b/c
lib/
  actions.ts              # Server Actions
  db.ts                   # Database client (singleton)
  auth.ts                 # Auth helpers
components/
  ui/                     # Shared UI components

Server vs Client Components

// SERVER COMPONENT (default) — runs on server only
// ✅ Can: async/await, access DB directly, use secrets
// ❌ Cannot: useState, useEffect, event handlers, browser APIs

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

export default async function UsersPage() {
  // Direct DB access — no API needed
  const users = await db.user.findMany({
    orderBy: { createdAt: "desc" },
    take: 20,
  });

  return (
    <div>
      <h1>Users</h1>
      {users.map(user => (
        <UserCard key={user.id} user={user} />
      ))}
    </div>
  );
}

// CLIENT COMPONENT — runs on server (for HTML) AND client
// ✅ Can: useState, useEffect, event handlers, browser APIs
// ❌ Cannot: async/await at component level, access secrets

"use client";

import { useState } from "react";

export function SearchBar({ onSearch }: { onSearch: (q: string) => void }) {
  const [query, setQuery] = useState("");

  return (
    <input
      value={query}
      => setQuery(e.target.value)}
      => e.key === "Enter" && onSearch(query)}
      placeholder="Search..."
    />
  );
}

Data Fetching & Caching

// fetch with caching options
async function getData(id: string) {
  // Static — cached indefinitely (default in static rendering)
  const static_data = await fetch(`https://api.example.com/static/${id}`);

  // Revalidate every 60 seconds (ISR equivalent)
  const revalidated = await fetch(`https://api.example.com/posts`, {
    next: { revalidate: 60 },
  });

  // Dynamic — never cache (always fresh)
  const dynamic_data = await fetch(`https://api.example.com/live/${id}`, {
    cache: "no-store",
  });

  return { static_data, revalidated, dynamic_data };
}

// Parallel data fetching — don't await sequentially
export default async function Page({ params }: { params: { id: string } }) {
  // ✅ Start both fetches simultaneously
  const [user, posts] = await Promise.all([
    getUser(params.id),
    getUserPosts(params.id),
  ]);

  return <Profile user={user} posts={posts} />;
}

// generateStaticParams — pre-render dynamic routes at build time
export async function generateStaticParams() {
  const posts = await db.post.findMany({ select: { slug: true } });
  return posts.map(post => ({ slug: post.slug }));
}

Streaming with Suspense

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

// Page renders immediately with shell
// Slow components stream in when ready
export default function DashboardPage() {
  return (
    <div>
      <h1>Dashboard</h1>

      {/* Renders immediately — no async */}
      <QuickStats />

      {/* Streams in after slow DB query */}
      <Suspense fallback={<RevenueChartSkeleton />}>
        <RevenueChart />    {/* async Server Component */}
      </Suspense>

      {/* Streams in independently */}
      <Suspense fallback={<ActivityFeedSkeleton />}>
        <ActivityFeed />    {/* async Server Component */}
      </Suspense>
    </div>
  );
}

// Async Server Component
async function RevenueChart() {
  // This slow query doesn't block the rest of the page
  const data = await db.order.aggregate({
    _sum: { total: true },
    groupBy: ["month"],
  });
  return <Chart data={data} />;
}

Server Actions

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

import { revalidatePath, revalidateTag } from "next/cache";
import { redirect } from "next/navigation";
import { z } from "zod";

const CreatePostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(10),
  published: z.boolean().default(false),
});

export async function createPost(formData: FormData) {
  // Validate
  const parsed = CreatePostSchema.safeParse({
    title: formData.get("title"),
    content: formData.get("content"),
    published: formData.get("published") === "on",
  });

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

  // Authorize
  const session = await getSession();
  if (!session) return { error: { _form: ["Unauthorized"] } };

  // Mutate
  const post = await db.post.create({
    data: { ...parsed.data, authorId: session.userId },
  });

  // Revalidate cache
  revalidatePath("/posts");
  revalidateTag("posts");

  // Redirect
  redirect(`/posts/${post.id}`);
}

// With useFormState for error display
"use client";
import { useFormState, useFormStatus } from "react-dom";
import { createPost } from "@/lib/actions";

const initialState = { error: null };

export function CreatePostForm() {
  const [state, formAction] = useFormState(createPost, initialState);

  return (
    <form action={formAction}>
      <input name="title" placeholder="Title" />
      {state.error?.title && <p>{state.error.title[0]}</p>}

      <textarea name="content" placeholder="Content" />
      {state.error?.content && <p>{state.error.content[0]}</p>}

      <SubmitButton />
    </form>
  );
}

function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Creating..." : "Create Post"}
    </button>
  );
}

Middleware

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

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

  // Auth check
  const token = request.cookies.get("session")?.value;
  const isAuthenticated = !!token; // validate token here

  const isProtectedRoute = pathname.startsWith("/dashboard");
  const isAuthRoute = pathname.startsWith("/login");

  if (isProtectedRoute && !isAuthenticated) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  if (isAuthRoute && isAuthenticated) {
    return NextResponse.redirect(new URL("/dashboard", request.url));
  }

  // Add request headers for downstream use
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set("x-pathname", pathname);

  return NextResponse.next({
    request: { headers: requestHeaders },
  });
}

// Only run middleware on these paths
export const config = {
  matcher: [
    "/((?!api|_next/static|_next/image|favicon.ico).*)",
  ],
};

Metadata API

// Static metadata
export const metadata: Metadata = {
  title: "My App",
  description: "My app description",
  openGraph: {
    title: "My App",
    description: "My app description",
    images: ["/og-image.png"],
  },
};

// Dynamic metadata
export async function generateMetadata(
  { params }: { params: { id: string } }
): Promise<Metadata> {
  const post = await getPost(params.id);
  if (!post) return { title: "Not Found" };

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [post.coverImage],
    },
  };
}

The Four Caching Layers

1. Request Memoization (per-render)
   - Deduplicates identical fetch() calls in the same render tree
   - Automatic — no configuration needed
   - Resets after each server request

2. Data Cache (persistent)
   - Stores fetch() responses on the server
   - Controlled by: cache: 'no-store' | next: { revalidate: N } | next: { tags: [] }
   - Persists across deployments until revalidated

3. Full Route Cache (build time)
   - Caches rendered HTML + RSC payload of static routes
   - Opt out with: export const dynamic = 'force-dynamic'
   - Revalidated with: revalidatePath() or revalidateTag()

4. Router Cache (client-side)
   - Caches RSC payloads in browser memory
   - Lasts 30s (dynamic) or 5min (static) by default
   - Cleared on: router.refresh() or server action completion

Best Practices

• Default to Server Components — only add use client when needed
• Fetch data as close to where it's used as possible — in the Server Component itself
• Use Promise.all() for parallel fetches — never sequential awaits
• Put Suspense boundaries around slow async components for streaming
• Use Server Actions for mutations — not API routes in App Router
• Validate and authorize in every Server Action — never trust the client
• Use revalidatePath or revalidateTag after mutations
• Use next/image for all images — automatic optimization
• Use next/font for fonts — eliminates layout shift

Common Pitfalls

Related Skills

• react-expert: For React hooks and patterns
• typescript-expert: For Next.js type safety
• postgresql-expert: For database with Next.js
• auth-expert: For authentication patterns
• webperf-expert: For Next.js performance optimization
• docker-expert: For self-hosting Next.js