Next.js 15 App Router: The Complete Developer Guide (2025)

I've built my last 8 projects with Next.js App Router. This guide covers everything I've learned — from basic concepts to production patterns that handle 50K+ users.

[Hero Image: Next.js 15 Logo Glow]

Sections:

1. App Router vs Pages Router (and when to migrate)
2. Server Components — The Mental Model Shift
3. Client Components — When and How
4. The "use client" Boundary — Getting It Right
5. Data Fetching Patterns (5 approaches compared)
6. Caching Deep Dive (the most confusing part, simplified)
7. Layouts, Templates, and Loading States
8. Error Handling & Not Found Pages
9. Middleware for Auth, Redirects, and i18n
10. Server Actions — Forms Without API Routes
11. Metadata & SEO (Dynamic OG Images, Sitemaps)
12. Authentication Patterns
13. Deployment & Performance Optimization
14. Migration Guide: Pages Router → App Router
15. Common Gotchas (And How to Fix Them)

[Full content for each section with code examples, diagrams, and benchmarks]

---

2. Server Components — The Mental Model Shift

In Next.js 15, components are Server Components by default. This is a massive shift.

Why Server Components?

• Zero Bundle Size: The code stays on the server.
• Direct Database Access: No need for API endpoints for initial data.
• Security: Sensitive keys stay on the server.
• Performance: Less JS for the browser to parse.

The "use client" Boundary

You only use Client Components when you need:

• Interactive features (onClick, onChange)
• Browser APIs (window, localStorage)
• State or Lifecycle hooks (useState, useEffect)

[Image: Server vs Client Components diagram]

---

5. Data Fetching Patterns

Next.js 15 offers 5 main ways to fetch data. Here's how they compare:

| Pattern | Where | Use Case | |---------|-------|----------| | Server Fetch | Server Component | Most common, fastest | | Route Handler | api/route.ts | Third-party access | | Server Action | action.ts | Form submissions, mutations | | SWR / React Query | Client Component | Real-time, polling | | Direct DB | Server Component | High performance, single DB |

[Image: Data Fetching Comparison chart]

---

6. Caching Deep Dive (The Onion Model)

Caching in Next.js 15 happens at multiple layers:

1. Request Memoization: Caches function calls within a single render pass.
2. Data Cache: Caches data across multiple requests and users.
3. Full Route Cache: Caches the rendered HTML and RSC payload.
4. Router Cache: Client-side cache of visited routes.

[Image: Caching Layers diagram]

---

[Continue with detailed explanations of remaining sections...]