Overview

// app/posts/page.tsx
async function PostsPage() {
  // => Server Component (default, no 'use client')
  // => Runs on server, has access to database
  const posts = await db.posts.findMany({
    // => Fetch all posts from database
    orderBy: { createdAt: 'desc' },
    // => Order by newest first
  });
  // => posts is Post[] array

  return (
    <ul>
      {/* => Map posts to list items */}
      {posts.map((post) => (
        // => post.id is unique identifier
        // => Used as React key for list rendering
        <li key={post.id}>
          {/* => Display post title */}
          {post.title}
          {/* => Renders: "My First Post" */}
        </li>
      ))}
    </ul>
  );
}

### Example N: Descriptive Title

2-3 sentence explanation of the concept.

```typescript
// Heavily annotated code example
// showing the Next.js pattern in action
```

**Code annotations**:

- `// =>` shows expected output, state changes, or results
- Inline comments explain what each line does
- Variable names are self-documenting
- Type annotations make data flow explicit

## What's Covered

### Core Next.js Concepts

- **App Router**: File-based routing, route groups, dynamic routes, catch-all routes
- **Server Components**: Default rendering, data fetching, database access
- **Client Components**: 'use client' directive, React hooks, event handlers
- **Server Actions**: Backend logic, form handling, mutations, progressive enhancement
- **Layouts**: Root layout, nested layouts, template vs layout

### Data Fetching & Rendering

- **Static Rendering (SSG)**: Build-time rendering, generateStaticParams, static export
- **Dynamic Rendering (SSR)**: Request-time rendering, dynamic data, cookies/headers
- **Incremental Static Regeneration (ISR)**: Time-based revalidation, on-demand revalidation
- **Streaming**: Loading UI, Suspense, progressive rendering
- **Caching**: Fetch caching, data cache, request memoization

### Routing Patterns

- **Pages & Layouts**: page.tsx, layout.tsx, template.tsx
- **Dynamic Routes**: [id], [...slug], [[...slug]] patterns
- **Route Handlers**: API routes in app/api/
- **Parallel Routes**: @folder convention, multiple routes same level
- **Intercepting Routes**: (.)folder, (..)folder, modal patterns

### Forms & Mutations

- **Server Actions**: Form actions, useFormStatus, useFormState
- **Validation**: Server-side validation, zod integration
- **Progressive Enhancement**: Works without JavaScript
- **Optimistic Updates**: Client-side optimism, error recovery

### TypeScript Integration

- **Type Safety**: Component props, Server Action types, API routes
- **Generic Components**: Generic Server/Client Components
- **Type Guards**: Runtime type checking, validation
- **Utility Types**: Next.js specific types (PageProps, LayoutProps, Metadata)

### Optimization

- **Image Optimization**: next/image, responsive images, lazy loading
- **Font Optimization**: next/font, Google Fonts, local fonts
- **Script Optimization**: next/script, loading strategies
- **Metadata**: SEO, OpenGraph, Twitter Cards, dynamic metadata

### Production Patterns

- **Authentication**: Auth.js/NextAuth, Clerk integration, protected routes
- **Database**: Prisma, Drizzle, direct SQL queries
- **Error Handling**: error.tsx, global-error.tsx, not-found.tsx
- **Loading States**: loading.tsx, Suspense boundaries, skeleton UI
- **Middleware**: Authentication, redirects, rewrites, A/B testing
- **Deployment**: Vercel, Docker, self-hosting, environment variables

## What's NOT Covered

We exclude topics that belong in specialized tutorials:

- **React Fundamentals**: JSX, components, props, state, hooks (see [React tutorial](/en/learn/software-engineering/platform-web/fe-react))
- **Advanced TypeScript**: Deep TypeScript features unrelated to Next.js
- **State Management Libraries**: Redux, Zustand (use React Context or Server State)
- **Testing Deep Dives**: Advanced testing strategies (separate testing tutorial)
- **Pages Router**: Legacy routing system (App Router only)
- **Webpack Configuration**: Build tool details (Next.js abstracts this)
- **React Native**: Mobile development (separate tutorial)

For these topics, see dedicated tutorials and framework documentation.

## Prerequisites

### Required

- **React fundamentals**: Components, props, state, hooks, JSX ([React tutorial](/en/learn/software-engineering/platform-web/fe-react))
- **JavaScript fundamentals**: ES6+ syntax, async/await, destructuring
- **TypeScript basics**: Basic types, interfaces, generics
- **HTML/CSS**: Basic web fundamentals, DOM concepts
- **Programming experience**: You've built applications before

### Recommended

- **Web APIs**: Fetch API, localStorage, FormData
- **Asynchronous JavaScript**: Promises, async/await patterns
- **Modern tooling**: npm/yarn, command-line basics
- **HTTP basics**: Request methods, status codes, headers

### Not Required

- **Next.js experience**: This guide assumes you're new to Next.js
- **Server-side development**: We teach server concepts as needed
- **Database knowledge**: Examples show patterns, not database administration
- **DevOps expertise**: Deployment patterns are simplified

## Getting Started

Before starting the examples, ensure you have basic environment setup:

1. **Master React**: [React by Example](/en/learn/software-engineering/platform-web/tools/fe-react/by-example) - Learn React fundamentals first (critical prerequisite)
2. **Review Initial Setup**: [Initial Setup](/en/learn/software-engineering/platform-web/tools/fe-nextjs/initial-setup) - Install Node.js, create Next.js project
3. **Try Quick Start**: [Quick Start](/en/learn/software-engineering/platform-web/tools/fe-nextjs/quick-start) - Build Zakat Calculator to understand Server Components and Server Actions

These tutorials provide hands-on foundation before diving into by-example learning.

## How to Use This Guide

### 1. Choose Your Starting Point

- **New to Next.js?** Start with Beginner (Example 1)
- **React experience** but new to Next.js? Start with Beginner (Example 1) - Server Components are different from plain React
- **Building specific feature?** Search for relevant example topic

**Important**: Even experienced React developers should start with Beginner examples. Next.js Server Components represent a paradigm shift from traditional React.

### 2. Read the Example

Each example has five parts:

- **Explanation** (2-3 sentences): What Next.js concept, why it exists, when to use it
- **Code** (heavily commented): Working TypeScript code showing the pattern
- **Key Takeaway** (1-2 sentences): Distilled essence of the pattern
- **Expected Output**: What you'll see when running the code
- **Common Pitfalls**: Mistakes to avoid

### 3. Run the Code

Create a test project and run each example:

```bash
npx create-next-app@latest nextjs-examples
cd nextjs-examples
# Choose: TypeScript, ESLint, Tailwind CSS, App Router
# Paste example code into app/page.tsx or create new route
npm run dev
```