Skip to content

MustafaKucukcoskun/Refine-agent-kit / .agents/skills/nextjs-app-router-patterns

nextjs-app-router-patterns

Verified

Next.js App Router patterns — directory structure, Server/Client Components, Server Actions, route groups, Metadata API, image/font optimization, configuration. Use when building Next.js 14+ apps with App Router.

Next.js App Router Patterns

Actionable patterns for Next.js 14+ App Router. No theory — code first.


1. Directory Structure

app/
├── layout.tsx          # Root layout (required) — wraps ALL pages
├── page.tsx            # Home page (/)
├── loading.tsx         # Loading UI (Suspense boundary)
├── error.tsx           # Error boundary (client component)
├── not-found.tsx       # 404 page
├── global-error.tsx    # Root error boundary
├── dashboard/
│   ├── layout.tsx      # Nested layout
│   ├── page.tsx        # /dashboard
│   └── settings/
│       └── page.tsx    # /dashboard/settings
├── (marketing)/        # Route Group — no URL segment
│   ├── about/page.tsx  # /about
│   └── blog/page.tsx   # /blog
├── @modal/             # Parallel Route (slot)
│   └── default.tsx
└── api/
    └── route.ts        # Route Handler (GET, POST, etc.)

Key Files

FilePurposeComponent Type
layout.tsxShared UI, persists across navigationsServer (default)
page.tsxUnique UI for a routeServer (default)
loading.tsxInstant loading stateServer
error.tsxError recovery UIClient (must be)
template.tsxLike layout but re-mounts on navigationServer
not-found.tsx404 UIServer

2. Server Components vs Client Components

Decision Rule

Default = Server Component (SC)
Add "use client" ONLY when you need:
├── useState, useEffect, useRef
├── onClick, onChange (event handlers)
├── Browser APIs (window, localStorage)
└── Third-party client libraries

Pattern

// Server Component (default) — can be async
export default async function ProductList() {
  const products = await db.product.findMany(); // Direct DB access
  return (
    <ul>
      {products.map((p) => (
        <li key={p.id}>
          <AddToCartButton productId={p.id} /> {/* Client boundary */}
        </li>
      ))}
    </ul>
  );
}
"use client"; // Client Component — for interactivity

import { useState } from "react";

export function AddToCartButton({ productId }: { productId: string }) {
  const [pending, setPending] = useState(false);
  return (
    <button onClick={() => setPending(true)} disabled={pending}>
      {pending ? "Adding..." : "Add to Cart"}
    </button>
  );
}

Rules

✅ Do❌ Don't
Keep "use client" at leaf componentsPut "use client" in layout.tsx
Pass serializable props to clientImport server-only code in client
Fetch data in SC, pass to CCFetch data in client useEffect
Use SC for static/SEO contentMake everything client for convenience

3. 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.post.create({ data: { title } });
  revalidatePath("/posts");
}
// app/posts/new/page.tsx — Server Component with form
import { createPost } from "@/app/actions";

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

With useActionState (client-side feedback)

"use client";

import { useActionState } from "react";
import { createPost } from "@/app/actions";

export function PostForm() {
  const [state, formAction, isPending] = useActionState(createPost, null);
  return (
    <form action={formAction}>
      <input name="title" required />
      <button disabled={isPending}>
        {isPending ? "Creating..." : "Create"}
      </button>
      {state?.error && <p>{state.error}</p>}
    </form>
  );
}

4. Route Groups & Parallel Routes

Route Groups (name) — organize without affecting URL

app/
├── (auth)/
│   ├── login/page.tsx    → /login
│   └── register/page.tsx → /register
├── (dashboard)/
│   ├── layout.tsx        → dashboard-specific layout
│   └── settings/page.tsx → /settings

Parallel Routes @slot — render multiple pages simultaneously

app/
├── layout.tsx           → receives {children, modal} as props
├── @modal/
│   ├── default.tsx      → rendered when no modal active
│   └── photo/[id]/page.tsx → /photo/123 in modal slot
└── page.tsx
// app/layout.tsx
export default function Layout({
  children,
  modal,
}: {
  children: React.ReactNode;
  modal: React.ReactNode;
}) {
  return (
    <>
      {children}
      {modal}
    </>
  );
}

5. Metadata API

Static Metadata

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

export const metadata: Metadata = {
  title: "About Us",
  description: "Learn about our company",
  openGraph: { title: "About Us", description: "..." },
};

Dynamic Metadata

// app/products/[id]/page.tsx
import type { Metadata } from "next";

type Props = { params: Promise<{ id: string }> };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { id } = await params;
  const product = await getProduct(id);
  return {
    title: product.name,
    description: product.description,
  };
}

6. Image & Font Optimization

next/image

import Image from "next/image";

// Local image (auto width/height)
import heroImg from "@/public/hero.webp";
<Image src={heroImg} alt="Hero" priority placeholder="blur" />

// Remote image (must specify dimensions)
<Image src="https://example.com/photo.jpg" alt="Photo" width={800} height={600} />

next/font

// app/layout.tsx
import { GeistSans, GeistMono } from "geist/font";
// OR with Google Fonts:
import { Outfit } from "next/font/google";

const outfit = Outfit({ subsets: ["latin"], variable: "--font-outfit" });

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

7. next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Image domains
  images: {
    remotePatterns: [{ protocol: "https", hostname: "example.com" }],
  },
  // Redirects
  async redirects() {
    return [{ source: "/old-path", destination: "/new-path", permanent: true }];
  },
  // Environment variables (public)
  env: {
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },
  // Experimental features
  experimental: {
    typedRoutes: true,
  },
};

export default nextConfig;

Quick Reference

TaskPattern
Data fetchingasync SC + direct DB/API call
Form mutationServer Action + revalidatePath
Loading stateloading.tsx or useActionState
Error handlingerror.tsx (client) + notFound()
SEOgenerateMetadata + <Image>
Shared layoutlayout.tsx (nests automatically)
Auth gateMiddleware (middleware.ts at root)
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall