Next.js App Router Cheatsheet
A modern master reference for Next.js (version 13, 14, and 15+) using the App Router, React Server Components (RSC), data fetching models, and optimized deployment architectures.
1. Directory Structure (App Router)
The App Router works via file-system-based routing rooted inside the app/ folder.
app/
├── layout.tsx # Root layout (required, holds html & body)
├── page.tsx # Home page route (/)
├── loading.tsx # Suspense fallback wrapper for page load
├── error.tsx # Error boundary wrapper for route segment
├── not-found.tsx # Custom 404 handler
├── about/
│ └── page.tsx # Sub-route (/about)
├── blog/
│ ├── [slug]/ # Dynamic path segment
│ │ └── page.tsx # Individual blog post route (/blog/hello-world)
│ └── page.tsx # Blog list route (/blog)
└── api/
└── route.ts # Backend route handler (/api)
2. Server Components vs. Client Components
In the App Router, components are React Server Components (RSC) by default unless prefixed with "use client".
| Feature | React Server Component (RSC) | Client Component |
|---|---|---|
| Default | Yes | No (requires "use client" at top) |
| Execution | Server-only (HTML rendered & streamed) | Pre-rendered on server, hydrated on client |
| Access to Hooks | No (no useState, useEffect, etc.) |
Yes (can use React state & effects) |
| Direct DB queries | Yes | No |
| Browser API access | No (no window, document, etc.) |
Yes |
| Bundle Size Impact | Zero (only the final markup is sent) | Includes bundle scripts for hydration |
Mixing Server and Client Components
- Keep Client Components at the leaves of your component tree.
- Pass Server Components as children to Client Components rather than importing them directly.
// GOOD: import ClientWrapper from "./ClientWrapper"; import ServerChild from "./ServerChild"; export default function Parent() { return ( <ClientWrapper> <ServerChild /> </ClientWrapper> ); }
3. Data Fetching & Caching
Data fetching in Next.js builds on the native Web fetch API, providing native memoization, cache control, and revalidation.
Server-Side Data Fetching (Static / SSR)
// This fetch runs on the server inside a Server Component
async function getPosts() {
const res = await fetch('https://api.example.com/posts');
if (!res.ok) throw new Error('Failed to fetch posts');
return res.json();
}
export default async function Blog() {
const posts = await getPosts();
return (
<ul>
{posts.map((post: any) => (
<li key={post.id}>{post.title}</li>
))}
</ul>
);
}
Fetch Strategies & Configurations
// 1. Force Cache (Static Site Generation - SSG)
fetch('https://api.example.com', { cache: 'force-cache' });
// 2. Bypass Cache (Server-Side Rendering - SSR)
fetch('https://api.example.com', { cache: 'no-store' });
// 3. Incremental Static Regeneration (ISR)
fetch('https://api.example.com', { next: { revalidate: 3600 } }); // revalidate hourly
Segment Route Parameters (RSC Config)
Place these variable definitions directly at the top of any route file (page.tsx, layout.tsx or route.ts) to configure behavior:
export const dynamic = 'force-dynamic'; // Force SSR
export const revalidate = 60; // Revalidate page every 60 seconds
export const fetchCache = 'force-cache';
4. Routing & Navigation
File-System Routes
- Dynamic Segments:
app/blog/[slug]/page.tsxresolves to/blog/some-slug.- Inside
page.tsx, parameters are accessed viaparams.slug(in async params context).
- Inside
- Catch-All Segments:
app/shop/[...slug]/page.tsxresolves to/shop/clothes,/shop/clothes/shirts. - Optional Catch-All:
app/shop/[[...slug]]/page.tsxalso resolves to/shop.
Client-Side Navigation
import Link from 'next/link';
export default function Home() {
return (
<Link href="/about" prefetch={true}>
About Page
</Link>
);
}
Imperative Navigation (Client Hooks)
"use client";
import { useRouter, usePathname, useSearchParams } from 'next/navigation';
export default function SearchForm() {
const router = useRouter();
const pathname = usePathname();
const searchParams = useSearchParams();
const handleSearch = (term: string) => {
router.push(`${pathname}?q=${term}`);
};
return <button onClick={() => handleSearch('react')}>Search</button>;
}
5. API Routes (Route Handlers)
Create custom request handlers for HTTP requests using the route.ts file name inside the API folder.
// app/api/users/route.ts
import { NextResponse } from 'next/server';
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const id = searchParams.get('id');
return NextResponse.json({ message: `Fetching user ${id}` });
}
export async function POST(request: Request) {
const body = await request.json();
// Perform database insert here
return NextResponse.json({ success: true, data: body }, { status: 201 });
}
6. Metadata API
Optimize SEO by defining static or dynamic metadata headers inside server layouts or pages.
Static Metadata
// app/about/page.tsx
import { Metadata } from 'next';
export const metadata: Metadata = {
title: 'About Us | Enterprise Solutions',
description: 'Learn more about our advanced tech stack and architecture.',
};
Dynamic Metadata
// app/blog/[slug]/page.tsx
import { Metadata } from 'next';
interface Props {
params: { slug: string };
}
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const product = await getProduct(params.slug);
return {
title: `${product.title} - Company Store`,
description: product.summary,
};
}
---
## 7. Next.js Server Actions
Server Actions are asynchronous functions that are executed on the server, but can be invoked directly inside client or server components (without manually building an API endpoint).
### Defining Server Actions
```typescript
// app/actions.ts
"use server";
import { revalidatePath } from 'next/cache';
export async function createPost(formData: FormData) {
const title = formData.get("title");
const content = formData.get("content");
// Write directly to your DB
await db.post.create({ data: { title, content } });
// Revalidate cache for the blog list page
revalidatePath('/blog');
}
Invoking Server Actions inside Client Components
// app/blog/new/page.tsx
"use client";
import { createPost } from '@/app/actions';
export default function NewPostForm() {
return (
<form action={createPost} class="space-y-4">
<input type="text" name="title" placeholder="Post Title" required class="border p-2" />
<textarea name="content" placeholder="Content" class="border p-2" />
<button type="submit" class="bg-blue-500 text-white p-2">Publish</button>
</form>
);
}
8. Middleware Reference
Middleware runs before a request is completed, allowing you to rewrite, redirect, or modify request headers.
// middleware.ts (defined in root of the project next to /app)
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
export function middleware(request: NextRequest) {
const token = request.cookies.get('session-token');
// If trying to access protected paths and not authenticated, redirect to login
if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url));
}
return NextResponse.next();
}
// Matching specific paths
export const config = {
matcher: ['/dashboard/:path*', '/api/secure/:path*'],
};
9. Next.js 15 Highlights
Next.js 15 introduces several major upgrades:
- Caching Changes:
fetchrequests, GET Route Handlers, and Client Router cache are now uncached by default (previously cached by default). - React 18 & 19 Support: Complete out-of-the-box compatibility with React 19’s Server Actions hook (
useActionState,useFormStatus). - Asynchronous Request APIs: APIs that rely on runtime request data are now asynchronous (e.g.
headers(),cookies(),paramsandsearchParamson pages).// Next.js 15 dynamic params usage: export default async function Page({ params }: { params: Promise<{ id: string }> }) { const { id } = await params; return <div>ID: {id}</div>; }
10. Next.js 15 Advanced Architectural Patterns
Partial Prerendering (PPR)
Partial Prerendering combines static layout compilation with dynamic page elements without loading overheads.
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
ppr: 'incremental', // Enable PPR incrementally on select routes
},
};
module.exports = nextConfig;
To enable PPR on a route, wrap dynamic child components inside standard React Suspense boundaries:
// app/store/page.tsx
import { Suspense } from 'react';
import StaticBanner from '@/components/StaticBanner';
import DynamicCartDetails from '@/components/DynamicCartDetails';
export const experimental_ppr = true; // Enable PPR on this specific route
export default function StorePage() {
return (
<main class="p-6">
<StaticBanner /> <!-- Pre-rendered statically at build time -->
<Suspense fallback={<div>Loading your cart details...</div>}>
<DynamicCartDetails /> <!-- Rendered dynamically on request -->
</Suspense>
</main>
);
}
Next.js 15 Caching Opt-Out Directives
Since fetch is uncached by default, explicit opt-in is required to persist cache states.
// 1. Force fetch cache globally/locally in Next 15:
const cachedData = await fetch('https://api.example.com', { cache: 'force-cache' });
// 2. Opt-out of client navigation caches:
export const dynamic = 'force-dynamic';
```