Next.js App Router - Modern Patterns

Purpose

Expert guidance for Next.js 15 App Router:

• Server Components - Default rendering strategy
• Client Components - Interactive UI patterns
• Server Actions - Form mutations & data updates
• Data Fetching - Caching & revalidation strategies
• Routing - Layouts, loading, error boundaries

Critical Rules

1. Server Components (Default)

Components are Server Components by default. Only add 'use client' when needed.

tsx
1// Server Component (default) - can access DB directly
2async function UserProfile({ userId }: { userId: string }) {
3	const user = await db.user.findUnique({ where: { id: userId } });
4	return <div>{user.name}</div>;
5}

2. Client Components (Interactive Only)

Only use 'use client' for interactivity (hooks, events, browser APIs).

tsx
1'use client';
2
3import { useState } from 'react';
4
5export function Counter() {
6	const [count, setCount] = useState(0);
7	return <button onClick={() => setCount(count + 1)}>{count}</button>;
8}

3. Server Actions (Mutations)

Use Server Actions for form submissions and data mutations.

tsx
1// app/actions.ts
2'use server';
3
4import { z } from 'zod';
5import { revalidatePath } from 'next/cache';
6
7const createUserSchema = z.object({
8	name: z.string().min(2),
9	email: z.string().email(),
10});
11
12export async function createUser(formData: FormData) {
13	const data = createUserSchema.parse({
14		name: formData.get('name'),
15		email: formData.get('email'),
16	});
17
18	await db.user.create({ data });
19	revalidatePath('/users');
20}

File Structure

app/
├── layout.tsx           # Root layout (required)
├── page.tsx            # Home page
├── loading.tsx         # Loading UI
├── error.tsx           # Error boundary
├── not-found.tsx       # 404 page
├── (auth)/             # Route group (no URL segment)
│   ├── login/page.tsx
│   └── register/page.tsx
├── dashboard/
│   ├── layout.tsx      # Nested layout
│   ├── page.tsx
│   └── [id]/           # Dynamic route
│       └── page.tsx
└── api/
    └── trpc/[trpc]/route.ts

Data Fetching Patterns

Static Data (Default)

tsx
1// Cached at build time
2async function getProducts() {
3	const res = await fetch('https://api.example.com/products');
4	return res.json();
5}

Dynamic Data

tsx
1// Always fresh
2async function getUser(id: string) {
3	const res = await fetch(`https://api.example.com/users/${id}`, {
4		cache: 'no-store',
5	});
6	return res.json();
7}

Revalidate on Interval

tsx
1// Revalidate every 60 seconds
2async function getPosts() {
3	const res = await fetch('https://api.example.com/posts', {
4		next: { revalidate: 60 },
5	});
6	return res.json();
7}

On-Demand Revalidation

tsx
1'use server';
2
3import { revalidatePath, revalidateTag } from 'next/cache';
4
5export async function updatePost(id: string) {
6  await db.post.update({ where: { id }, data: { ... } });
7
8  revalidatePath('/posts');           // Revalidate path
9  revalidateTag('posts');             // Revalidate tag
10}

Loading & Error States

Loading UI

tsx
1// app/dashboard/loading.tsx
2export default function Loading() {
3	return <DashboardSkeleton />;
4}

Error Boundary

tsx
1// app/dashboard/error.tsx
2'use client';
3
4export default function Error({ error, reset }: { error: Error; reset: () => void }) {
5	return (
6		<div>
7			<h2>Something went wrong!</h2>
8			<button onClick={() => reset()}>Try again</button>
9		</div>
10	);
11}

Metadata & SEO

Static Metadata

tsx
1// app/page.tsx
2import type { Metadata } from 'next';
3
4export const metadata: Metadata = {
5	title: 'Home | MyApp',
6	description: 'Welcome to MyApp',
7};

Dynamic Metadata

tsx
1// app/products/[id]/page.tsx
2import type { Metadata } from 'next';
3
4export async function generateMetadata({ params }: { params: { id: string } }): Promise<Metadata> {
5	const product = await getProduct(params.id);
6	return {
7		title: product.name,
8		description: product.description,
9	};
10}

Route Handlers (API)

tsx
1// app/api/users/route.ts
2import { NextResponse } from 'next/server';
3
4export async function GET() {
5	const users = await db.user.findMany();
6	return NextResponse.json(users);
7}
8
9export async function POST(request: Request) {
10	const body = await request.json();
11	const user = await db.user.create({ data: body });
12	return NextResponse.json(user, { status: 201 });
13}

Middleware

tsx
1// middleware.ts (root)
2import { NextResponse } from 'next/server';
3import type { NextRequest } from 'next/server';
4
5export function middleware(request: NextRequest) {
6	// Check auth
7	const token = request.cookies.get('token');
8
9	if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
10		return NextResponse.redirect(new URL('/login', request.url));
11	}
12
13	return NextResponse.next();
14}
15
16export const config = {
17	matcher: ['/dashboard/:path*'],
18};

Common Patterns

Parallel Data Fetching

tsx
1async function Dashboard() {
2	// Fetch in parallel
3	const [user, posts, notifications] = await Promise.all([
4		getUser(),
5		getPosts(),
6		getNotifications(),
7	]);
8
9	return (
10		<div>
11			<UserCard user={user} />
12			<PostList posts={posts} />
13			<NotificationBell count={notifications.length} />
14		</div>
15	);
16}

Streaming with Suspense

tsx
1import { Suspense } from 'react';
2
3export default function Page() {
4	return (
5		<div>
6			<h1>Dashboard</h1>
7			<Suspense fallback={<UserSkeleton />}>
8				<UserProfile />
9			</Suspense>
10			<Suspense fallback={<PostsSkeleton />}>
11				<RecentPosts />
12			</Suspense>
13		</div>
14	);
15}

Agent Integration

This skill is used by:

• nextjs-expert subagent
• orchestrator for routing Next.js tasks
• ui-mobile/tablet/desktop for platform-specific pages

FORBIDDEN

1. 'use client' without reason - Default is server
2. useEffect for data fetching - Use async components
3. getServerSideProps/getStaticProps - App Router uses async components
4. API routes for internal data - Use Server Components directly
5. Client-side auth checks only - Use middleware

Version

• v1.0.0 - Initial implementation based on Next.js 15 patterns