NextJS Comprehensive Guide

This learning guide is designed for software engineers who have foundational knowledge of web development (HTML, CSS, JavaScript) and a basic understanding of React, or experience with a stable version of Next.js released approximately 2-3 years ago (e.g., Next.js 12 or early Next.js 13). We will focus on Next.js 15, the latest stable release, and touch upon upcoming features in Next.js 16 to provide a comprehensive and forward-looking perspective.

Chapter 1: Next.js Fundamentals Refresher and Modern Setup

1.1: Understanding Next.js’s Core Value Proposition

Next.js is a React framework for building full-stack web applications. It extends React’s capabilities by providing a structured approach to common application requirements like routing, data fetching, and rendering. Its core value lies in offering a “batteries-included” experience that simplifies development while ensuring high performance, excellent SEO, and a great developer experience.

Next.js addresses common pain points of traditional single-page applications (SPAs) built solely with React, such as slow initial page loads, poor SEO, and complex data fetching patterns. It achieves this through various rendering strategies, including Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR), along with the new App Router’s emphasis on React Server Components.

1.2: Setting Up a Modern Next.js 15 Project

Next.js 15 is the latest stable release (as of August 2025), building upon the innovations introduced in Next.js 13 and 14. Key highlights include stable Server Actions, Turbopack as the default dev server, and continued advancements in the App Router.

To start a new Next.js 15 project:

npx create-next-app@latest my-nextjs-app

Follow the prompts. It is recommended to enable TypeScript, ESLint, and the App Router for a modern setup.

To upgrade an existing project to Next.js 15:

npm install next@latest react@latest react-dom@latest
# or
pnpm install next@latest react@latest react-dom@latest
# or
yarn add next@latest react@latest react-dom@latest

After upgrading, run the automated codemod for potential migrations:

npx @next/codemod@canary upgrade-latest

1.3: Pages Router vs. App Router: A Paradigm Shift

Next.js 13 introduced the App Router as a new routing and rendering paradigm, designed to leverage React Server Components. It is now the recommended approach, while the Pages Router (the traditional Next.js routing system) is maintained for backward compatibility.

Pages Router (legacy):

• Uses a pages/ directory for routing.
• Relies on getStaticProps, getServerSideProps, and getInitialProps for data fetching.
• Primarily client-side rendered by default, with opt-in server-side rendering or static generation.
• API routes are defined in pages/api/.

App Router (modern):

• Uses an app/ directory for routing.
• Builds upon React Server Components by default, allowing you to fetch data and render UI on the server.
• Simplifies data fetching with async/await directly in components.
• Introduces file conventions like layout.tsx, page.tsx, loading.tsx, error.tsx, and route.ts.
• Enables Server Actions for server-side mutations and form handling.
• Offers advanced streaming and Partial Prerendering capabilities.

The App Router is a significant evolution, aiming to unify server and client logic, improve performance, and simplify the developer experience by bringing more capabilities to the server. For any new project, it is strongly recommended to use the App Router.

Chapter 2: The App Router Deep Dive

The App Router reimagines routing, data fetching, and rendering in Next.js, making server-first rendering the default and deeply integrating React Server Components.

2.1: Anatomy of the App Router

The app directory uses a file-system based routing system with special files for defining UI and logic:

• 2.1.1: layout.tsx

  • What it is: A React component that defines the shared UI for a segment and its children. Layouts persist across navigations, meaning they don’t re-render.

  • Why it was introduced: To simplify the creation of consistent layouts across multiple pages without prop drilling or duplicating code, while benefiting from server-side rendering.

  • How it works: It receives a children prop, which will be populated by the page.tsx or nested layout.tsx files within its segment.

  • Example (Simple):

    // app/dashboard/layout.tsx
    import Link from 'next/link';
    
    export default function DashboardLayout({
      children,
    }: {
      children: React.ReactNode;
    }) {
      return (
        <div>
          <nav>
            <Link href="/dashboard">Overview</Link>
            <Link href="/dashboard/settings">Settings</Link>
          </nav>
          <main>{children}</main>
        </div>
      );
    }
    

  • Example (Complex: Nested Layouts): You can nest layouts by placing layout.tsx files in subfolders within the app directory.

    // app/layout.tsx (Root Layout)
    import './globals.css';
    
    export default function RootLayout({
      children,
    }: {
      children: React.ReactNode;
    }) {
      return (
        <html lang="en">
          <body>{children}</body>
        </html>
      );
    }
    
    // app/dashboard/layout.tsx (Nested Layout for dashboard)
    import Link from 'next/link';
    
    export default function DashboardLayout({
      children,
    }: {
      children: React.ReactNode;
    }) {
      return (
        <div className="flex">
          <aside className="w-64 p-4">
            <nav>
              <ul className="space-y-2">
                <li><Link href="/dashboard">Overview</Link></li>
                <li><Link href="/dashboard/settings">Settings</Link></li>
                <li><Link href="/dashboard/reports">Reports</Link></li>
              </ul>
            </nav>
          </aside>
          <main className="flex-1 p-4">{children}</main>
        </div>
      );
    }
    

    Tips: Root layout.tsx must contain <html> and <body> tags. Layouts are Server Components by default.

• 2.1.2: page.tsx

  • What it is: A React component that exports a page component, making the route segment publicly accessible.

  • Why it was introduced: It’s the primary way to define the unique content for a given route, working in conjunction with layouts.

  • How it works: It’s a Server Component by default and can be async to fetch data directly.

  • Example:

    // app/dashboard/page.tsx
    // This is a Server Component, can be async to fetch data
    export default async function DashboardPage() {
      const userData = await fetch('https://api.example.com/user/1').then(res => res.json());
    
      return (
        <div className="p-4">
          <h1 className="text-2xl font-bold">Welcome, {userData.name}!</h1>
          <p>Your email: {userData.email}</p>
          {/* More dashboard content */}
        </div>
      );
    }
    

• 2.1.3: loading.tsx

  • What it is: A component that provides a loading UI for a route segment while its content is being fetched and rendered on the server.

  • Why it was introduced: To improve perceived performance and user experience by showing an instant loading state, leveraging React Suspense. This prevents a blank screen while data is loading.

  • How it works: It automatically wraps its sibling page.tsx and any nested children in a Suspense boundary.

  • Example:

    // app/dashboard/loading.tsx
    export default function Loading() {
      return (
        <div className="p-4 text-center text-gray-500">
          Loading dashboard content...
          <div className="spinner mt-2"></div>
        </div>
      );
    }
    

• 2.1.4: error.tsx

  • What it is: A React Client Component that acts as an error boundary for a route segment. It catches unexpected runtime errors in Server and Client Components.

  • Why it was introduced: To gracefully handle errors, prevent the entire application from crashing, and provide a user-friendly fallback UI.

  • How it works: It must be a Client Component ('use client') and receives error and reset props.

  • Example:

    // app/dashboard/error.tsx
    'use client'; // Error boundaries must be Client Components
    
    import { useEffect } from 'react';
    
    export default function Error({
      error,
      reset,
    }: {
      error: Error & { digest?: string };
      reset: () => void;
    }) {
      useEffect(() => {
        // Log the error to an error reporting service
        console.error(error);
      }, [error]);
    
      return (
        <div className="p-4 text-center text-red-600">
          <h2 className="text-xl font-bold">Something went wrong!</h2>
          <p className="text-sm mt-2">{error.message}</p>
          <button
            className="mt-4 px-4 py-2 bg-blue-500 text-white rounded"
            onClick={
              // Attempt to recover by trying to re-render the segment
              () => reset()
            }
          >
            Try again
          </button>
        </div>
      );
    }
    

    Tips: Place error.tsx as high as possible in the component tree to catch more errors, but not so high that it catches expected errors for small, isolated components.

• 2.1.5: not-found.tsx

  • What it is: A component that renders a not-found UI when the notFound() function is called or an invalid route is accessed.

  • Why it was introduced: To provide custom 404 pages within specific route segments, improving user experience and consistency.

  • How it works: When notFound() is called from a Server Component (e.g., in data fetching), Next.js stops rendering the current route and renders the closest not-found.tsx.

  • Example:

    // app/products/[id]/not-found.tsx
    import Link from 'next/link';
    
    export default function NotFound() {
      return (
        <div className="p-4 text-center">
          <h2 className="text-xl font-bold">Product Not Found</h2>
          <p className="mt-2">Could not find the requested product.</p>
          <Link href="/products" className="text-blue-500 hover:underline mt-4 block">
            Return to Products
          </Link>
        </div>
      );
    }
    
    // Usage in a page:
    // app/products/[id]/page.tsx
    import { notFound } from 'next/navigation';
    
    async function getProduct(id: string) {
      const res = await fetch(`https://api.example.com/products/${id}`);
      if (!res.ok) {
        if (res.status === 404) {
          notFound(); // Call notFound() if product doesn't exist
        }
        throw new Error('Failed to fetch product');
      }
      return res.json();
    }
    
    export default async function ProductPage({ params }: { params: { id: string } }) {
      const product = await getProduct(params.id);
      return (
        <div className="p-4">
          <h1 className="text-2xl font-bold">{product.name}</h1>
          <p>{product.description}</p>
        </div>
      );
    }
    

• 2.1.6: template.tsx

  • What it is: A specialized React component that wraps each of its children, causing it to re-render and re-mount on navigation.

  • Why it was introduced: Unlike layout.tsx (which persists state), template.tsx is useful for scenarios where component state or effects need to be reset on navigation (e.g., for animations or certain data fetches).

  • How it works: It receives a children prop and creates a new instance of itself for each navigation within its subtree.

  • Example:

    // app/dashboard/template.tsx
    'use client'; // Can be a Client Component if it needs client-side effects
    
    import { useEffect, useState } from 'react';
    
    export default function DashboardTemplate({
      children,
    }: {
      children: React.ReactNode;
    }) {
      const [count, setCount] = useState(0);
    
      useEffect(() => {
        console.log('Template re-rendered and re-mounted:', count);
        // This effect will run every time you navigate within /dashboard
        setCount(prev => prev + 1);
      }, [children]); // Trigger effect on children change (navigation)
    
      return (
        <div>
          <p>Template render count: {count}</p>
          {children}
        </div>
      );
    }
    

    Tips: Use template.tsx sparingly, only when you specifically need the re-mounting behavior.

2.2: Nested Routing and Layouts

The App Router’s directory structure directly maps to URL segments, allowing for deeply nested routes and shared layouts.

app/
├── layout.tsx         // Root layout, applies to all routes
├── page.tsx           // Home page (/)
├── dashboard/
│   ├── layout.tsx     // Dashboard layout, applies to /dashboard and its sub-routes
│   ├── page.tsx       // Dashboard overview page (/dashboard)
│   └── settings/
│       ├── layout.tsx // Settings layout, applies to /dashboard/settings and its sub-routes
│       └── page.tsx   // Settings main page (/dashboard/settings)
├── products/
│   ├── page.tsx       // Products listing page (/products)
│   ├── [id]/          // Dynamic route segment for individual products
│   │   ├── page.tsx   // Individual product page (/products/123)
│   │   └── reviews/
│   │       └── page.tsx // Product reviews page (/products/123/reviews)
└── api/                // Route Handlers (API Routes)
    └── users/
        └── route.ts   // API endpoint for /api/users

In this structure:

• The RootLayout (app/layout.tsx) wraps the entire application.
• The DashboardLayout (app/dashboard/layout.tsx) wraps /dashboard and all its sub-pages (e.g., /dashboard/settings, /dashboard/reports).
• The SettingsLayout (app/dashboard/settings/layout.tsx) would only apply to /dashboard/settings and any deeper nested routes within settings.

This hierarchical structure allows for powerful composition of UI and data fetching across different parts of your application.

2.3: Dynamic Routes in the App Router

Dynamic routes allow you to create pages or API routes whose paths are determined at request time. This is achieved by enclosing a folder name in square brackets [].

• Example (Dynamic Page): To create a page for individual products, you would have app/products/[id]/page.tsx.

  // app/products/[id]/page.tsx
  interface ProductPageProps {
    params: {
      id: string; // The dynamic segment from the URL
    };
    searchParams: { [key: string]: string | string[] | undefined }; // Query parameters
  }
  
  export default async function ProductPage({ params }: ProductPageProps) {
    const productId = params.id;
    const product = await fetch(`https://api.example.com/products/${productId}`).then(res => res.json());
  
    return (
      <div className="p-4">
        <h1 className="text-3xl font-bold">{product.name}</h1>
        <p className="text-gray-700">{product.description}</p>
        <p className="text-xl mt-4">${product.price}</p>
      </div>
    );
  }
  

  Tips: The params object in component props will contain the values of dynamic segments.

• Example (Catch-all Dynamic Routes): To handle all routes under a specific path, use [...slug] (e.g., app/docs/[...slug]/page.tsx). This collects all segments after docs into a single slug array.

  // app/docs/[...slug]/page.tsx
  interface DocPageProps {
    params: {
      slug: string[]; // e.g., ['getting-started', 'installation'] for /docs/getting-started/installation
    };
  }
  
  export default function DocPage({ params }: DocPageProps) {
    const pathSegments = params.slug.join('/'); // Reconstruct the path
  
    return (
      <div className="p-4">
        <h1 className="text-3xl font-bold">Documentation for: {pathSegments}</h1>
        {/* Fetch content based on pathSegments */}
      </div>
    );
  }
  

• Example (Optional Catch-all Dynamic Routes): Use [[...slug]] (double brackets) to make the catch-all segment optional. For example, app/shop/[[...category]]/page.tsx would match /shop and /shop/electronics/laptops.

• Generating Static Params with generateStaticParams: For dynamic routes that you want to pre-render at build time (like blog posts or product pages), you can export an async function generateStaticParams() from your dynamic route page.tsx or layout.tsx. This function returns an array of params objects, which Next.js uses to generate static pages.

  // app/blog/[slug]/page.tsx
  import { notFound } from 'next/navigation';
  
  // This function runs at build time
  export async function generateStaticParams() {
    const posts = await fetch('https://api.example.com/blog/posts').then((res) => res.json());
  
    return posts.map((post: { slug: string }) => ({
      slug: post.slug,
    }));
  }
  
  interface BlogPostPageProps {
    params: {
      slug: string;
    };
  }
  
  export default async function BlogPostPage({ params }: BlogPostPageProps) {
    const post = await fetch(`https://api.example.com/blog/posts/${params.slug}`).then((res) => {
      if (res.status === 404) {
        notFound();
      }
      return res.json();
    });
  
    return (
      <article className="p-4">
        <h1 className="text-3xl font-bold">{post.title}</h1>
        <div className="prose mt-4" dangerouslySetInnerHTML={{ __html: post.content }} />
      </article>
    );
  }
  

  Tips: generateStaticParams is crucial for hybrid rendering models where you want the benefits of static delivery for certain dynamic paths.

Chapter 3: Server Components and Client Components

The distinction between Server and Client Components is fundamental to the App Router. They dictate where your code runs and how it interacts with the environment.

3.1: The use client and use server Directives

• 'use client':

  • What it is: A directive placed at the very top of a file (before any imports) to mark it as a Client Component.

  • Why it was introduced: To explicitly tell React that this component (and all its imported children) should be rendered on the client. This is necessary for components that rely on browser-specific APIs (like window, localStorage), user interactivity (event handlers like onClick, onChange), or React Hooks that manage client-side state (useState, useEffect).

  • How it works: Once a file has 'use client', all modules imported into it, including child components, are considered part of the client bundle.

  • Example:

    // components/Counter.tsx
    'use client'; // This component runs on the client
    
    import { useState } from 'react';
    
    export default function Counter() {
      const [count, setCount] = useState(0);
    
      return (
        <button
          onClick={() => setCount(count + 1)}
          className="px-4 py-2 bg-purple-500 text-white rounded hover:bg-purple-600"
        >
          Count: {count}
        </button>
      );
    }
    

• 'use server':

  • What it is: A directive placed at the very top of a file (before any imports) to mark all exported functions within that file as Server Actions, allowing them to be called directly from Client Components or forms. It can also be placed inside an async function (e.g., in page.tsx) to define an inline Server Action.

  • Why it was introduced: To enable direct invocation of server-side code from the client without manually creating API routes. This simplifies mutations, database interactions, and other server-side logic, while reducing client-side JavaScript.

  • How it works: Functions marked with 'use server' are executed securely on the server. Next.js handles the network communication to invoke these functions.

  • Example (Standalone Server Action file):

    // actions/posts.ts
    'use server';
    
    import { db } from '@/lib/db'; // Assuming a database client
    
    export async function createPost(formData: FormData) {
      const title = formData.get('title') as string;
      const content = formData.get('content') as string;
    
      if (!title || !content) {
        return { error: 'Title and content are required.' };
      }
    
      try {
        const newPost = await db.post.create({
          data: { title, content },
        });
        console.log('New post created:', newPost);
        return { success: true, post: newPost };
      } catch (error) {
        console.error('Failed to create post:', error);
        return { error: 'Failed to create post.' };
      }
    }
    

  • Example (Inline Server Action in a Server Component):

    // app/dashboard/page.tsx
    import { revalidatePath } from 'next/cache';
    
    export default function DashboardPage() {
      async function addDashboardItem(formData: FormData) {
        'use server'; // Inline Server Action
    
        const itemText = formData.get('itemText') as string;
        // Perform server-side logic, e.g., save to DB
        console.log('Adding item:', itemText);
    
        // Revalidate the current path to show updated data
        revalidatePath('/dashboard');
      }
    
      return (
        <form action={addDashboardItem}>
          <input type="text" name="itemText" placeholder="New dashboard item" />
          <button type="submit">Add Item</button>
        </form>
      );
    }
    

    Tips: Use revalidatePath or revalidateTag within Server Actions to update cached data and trigger a re-render of affected parts of your UI.

3.2: When to Use Which: Server vs. Client Components

Deciding between Server and Client Components is crucial for performance, security, and maintainability.

Use Client Components When You Need:

• Interactivity: State (useState), effects (useEffect), and event listeners (onClick, onChange).
• Browser-only APIs: window, document, localStorage, Navigator.geolocation, etc.
• Custom Hooks: Hooks that rely on client-side features.
• Third-party libraries: That depend on browser APIs or React Hooks (e.g., charting libraries, UI component libraries that manage their own state).

Use Server Components When You Need:

• Data Fetching: Direct database queries (e.g., Prisma, Drizzle ORM) or fetch calls to internal/external APIs, executed closer to the data source. This minimizes client-server waterfalls.
• Access to Sensitive Data/Secrets: API keys, tokens, database credentials, which should never be exposed to the client.
• Reduced Client-Side JavaScript Bundle Size: Only the rendered HTML is sent to the client, not the component’s JavaScript, leading to faster initial loads.
• Improved Initial Page Load (FCP, LCP): Content is rendered on the server and sent as HTML, improving metrics like First Contentful Paint and Largest Contentful Paint.
• SEO: Search engines can easily crawl fully rendered HTML.
• Large Dependencies: Keep heavy libraries on the server to avoid shipping them to the client.

Comparison Table:

3.3: Passing Data and Interleaving Components

You can pass data from Server Components to Client Components via props. It’s crucial that these props are serializable (e.g., plain objects, strings, numbers, arrays, functions marked with 'use server' or those that can be safely sent over the network).

Interleaving (Server Components as children of Client Components): This powerful pattern allows you to visually nest server-rendered UI within Client Components. The key is to pass Server Components as children (or other props) to a Client Component. The Server Components will be rendered on the server first, and only their resulting HTML (or a placeholder if suspense is involved) is passed to the Client Component for eventual hydration.

// components/Modal.tsx (Client Component)
'use client';

import { useState } from 'react';

export default function Modal({ children }: { children: React.ReactNode }) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Modal</button>
      {isOpen && (
        <div className="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center">
          <div className="bg-white p-6 rounded-lg">
            <button onClick={() => setIsOpen(false)} className="float-right">X</button>
            {children} {/* Server Component content will render here */}
          </div>
        </div>
      )}
    </>
  );
}

// app/page.tsx (Server Component)
import Modal from '@/components/Modal';
import LatestNews from '@/components/LatestNews'; // This could be a Server Component

export default function HomePage() {
  return (
    <div>
      <h1>Welcome to My App</h1>
      <Modal>
        {/* LatestNews is a Server Component, rendered on the server
            before being passed into the client-side Modal */}
        <LatestNews />
        <p className="mt-4">This content is inside the modal.</p>
      </Modal>
      {/* Other page content */}
    </div>
  );
}

// components/LatestNews.tsx (Server Component - no 'use client')
export default async function LatestNews() {
  const news = await fetch('https://api.example.com/news').then(res => res.json());
  return (
    <div className="border p-4 mt-4">
      <h2 className="text-xl font-bold">Latest News (Server Component)</h2>
      <ul>
        {news.map((item: any) => (
          <li key={item.id}>{item.title}</li>
        ))}
      </ul>
    </div>
  );
}

Tips: This pattern is essential for reducing client-side JavaScript, as the heavy lifting of LatestNews is done on the server, even though it appears within a client-interactive Modal.

3.4: Context Providers with Server and Client Components

React Context is a client-side feature and is not supported directly in Server Components. To use Context, you must define your Context Provider in a Client Component.

// app/providers/ThemeProvider.tsx
'use client';

import { createContext, useContext, useState, useEffect } from 'react';

type Theme = 'light' | 'dark';

interface ThemeContextType {
  theme: Theme;
  toggleTheme: () => void;
}

const ThemeContext = createContext<ThemeContextType | undefined>(undefined);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('light'); // Client-side state

  useEffect(() => {
    // Read theme from localStorage on mount (client-only)
    const savedTheme = localStorage.getItem('theme') as Theme;
    if (savedTheme) {
      setTheme(savedTheme);
      document.documentElement.classList.toggle('dark', savedTheme === 'dark');
    }
  }, []);

  const toggleTheme = () => {
    setTheme((prevTheme) => {
      const newTheme = prevTheme === 'light' ? 'dark' : 'light';
      localStorage.setItem('theme', newTheme);
      document.documentElement.classList.toggle('dark', newTheme === 'dark');
      return newTheme;
    });
  };

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme() {
  const context = useContext(ThemeContext);
  if (context === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
}

Then, import and wrap your layout (which is a Server Component) or specific Client Components with this provider:

// app/layout.tsx (Root Layout - Server Component)
import './globals.css';
import { ThemeProvider } from './providers/ThemeProvider'; // Client Component provider

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>
          {/* Children here can be Server or Client Components */}
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Any Client Component children within ThemeProvider can now use useTheme(). Server Components higher up or as siblings to the ThemeProvider will not have access to its context.

Chapter 4: Data Fetching and Caching Strategies

Next.js 15, especially with the App Router, provides powerful and flexible ways to fetch and cache data, simplifying complex patterns.

4.1: Data Fetching in Server Components (fetch and ORMs)

In Server Components, you can use async/await directly, treating data fetching as a natural part of rendering.

• With the fetch API: Next.js extends the native fetch API to include automatic caching and revalidation behaviors.

  // app/dashboard/products/page.tsx (Server Component)
  async function getProducts() {
    // Data will be cached by default for 'force-cache' if not opt-out
    // next: { revalidate: false } is the default, equivalent to 'force-cache'
    const res = await fetch('https://api.example.com/products');
  
    if (!res.ok) {
      throw new Error('Failed to fetch products');
    }
    return res.json();
  }
  
  export default async function ProductsPage() {
    const products = await getProducts();
  
    return (
      <div className="p-4">
        <h1 className="text-2xl font-bold">Product Catalog</h1>
        <ul>
          {products.map((product: any) => (
            <li key={product.id}>
              {product.name} - ${product.price}
            </li>
          ))}
        </ul>
      </div>
    );
  }
  

  • Caching Options for fetch:
    • cache: 'force-cache' (default): Cache indefinitely (until invalidated or next build).
    • cache: 'no-store': Always fetch fresh data (opts into dynamic rendering).
    • next: { revalidate: <seconds> }: Cache for a specific duration, then revalidate (ISR).
    • next: { tags: ['tag1', 'tag2'] }: Associate tags for manual revalidation (via revalidateTag).

  // Example with revalidation
  async function getLatestArticles() {
    const res = await fetch('https://api.example.com/articles', {
      next: { revalidate: 3600 } // Revalidate every hour
    });
    return res.json();
  }
  
  // Example with no-store (dynamic)
  async function getUserSpecificDashboardData(userId: string) {
    const res = await fetch(`https://api.example.com/dashboard/${userId}`, {
      cache: 'no-store' // Always fetch fresh data for this user
    });
    return res.json();
  }
  

• With an ORM or Database Client: Since Server Components run on the server, you can directly interact with your database using an ORM (like Prisma, Drizzle) or a database client.

  // lib/db.ts (Example Prisma client setup)
  import { PrismaClient } from '@prisma/client';
  export const prisma = new PrismaClient();
  
  // app/users/[id]/page.tsx (Server Component)
  import { prisma } from '@/lib/db';
  import { notFound } from 'next/navigation';
  
  export default async function UserProfilePage({ params }: { params: { id: string } }) {
    const user = await prisma.user.findUnique({
      where: { id: parseInt(params.id) },
      include: { posts: true },
    });
  
    if (!user) {
      notFound();
    }
  
    return (
      <div className="p-4">
        <h1 className="text-2xl font-bold">{user.name}</h1>
        <p>Email: {user.email}</p>
        <h2 className="text-xl mt-4">Posts by {user.name}</h2>
        <ul>
          {user.posts.map((post: any) => (
            <li key={post.id}>{post.title}</li>
          ))}
        </ul>
      </div>
    );
  }
  

  Tips: For database queries within Server Components, use React.cache from the experimental React canary channel (which Next.js App Router utilizes) to deduplicate requests.

  // lib/data-access.ts
  import { cache } from 'react';
  import { prisma } from './db';
  
  export const getCachedUser = cache(async (id: number) => {
    console.log(`Fetching user ${id} from DB (this should log once per request if cached)`);
    return prisma.user.findUnique({
      where: { id },
    });
  });
  

4.2: Data Fetching in Client Components (useEffect, SWR, React Query)

Client Components still use traditional React data fetching patterns, typically involving useEffect or dedicated data fetching libraries. This usually involves fetching from API Routes (Route Handlers) or external APIs.

• Using useEffect: For simple data fetching that needs to run on the client after the component mounts.

  // components/ClientPostsList.tsx
  'use client';
  
  import { useState, useEffect } from 'react';
  
  interface Post {
    id: number;
    title: string;
    body: string;
  }
  
  export default function ClientPostsList() {
    const [posts, setPosts] = useState<Post[]>([]);
    const [loading, setLoading] = useState(true);
    const [error, setError] = useState<string | null>(null);
  
    useEffect(() => {
      async function fetchPosts() {
        try {
          const res = await fetch('/api/posts'); // Fetch from your Next.js API Route
          if (!res.ok) {
            throw new Error(`HTTP error! status: ${res.status}`);
          }
          const data = await res.json();
          setPosts(data);
        } catch (err: any) {
          setError(err.message);
        } finally {
          setLoading(false);
        }
      }
      fetchPosts();
    }, []); // Empty dependency array means this runs once on mount
  
    if (loading) return <p>Loading posts...</p>;
    if (error) return <p className="text-red-500">Error: {error}</p>;
  
    return (
      <div className="p-4">
        <h2 className="text-xl font-bold">Client-Side Posts</h2>
        <ul>
          {posts.map((post) => (
            <li key={post.id}>
              <strong>{post.title}</strong>: {post.body.substring(0, 50)}...
            </li>
          ))}
        </ul>
      </div>
    );
  }
  

• Using SWR (Stale-While-Revalidate): SWR is a React Hooks library for data fetching. It’s excellent for caching, revalidation on focus/interval, and handling loading/error states.

  // components/PostsWithSWR.tsx
  'use client';
  
  import useSWR from 'swr';
  
  interface Post {
    id: number;
    title: string;
    body: string;
  }
  
  const fetcher = (url: string) => fetch(url).then(res => res.json());
  
  export default function PostsWithSWR() {
    const { data, error, isLoading } = useSWR<Post[]>('/api/posts', fetcher, {
      refreshInterval: 5000, // Revalidate every 5 seconds
      revalidateOnFocus: true, // Revalidate when window gains focus
    });
  
    if (isLoading) return <p>Loading posts with SWR...</p>;
    if (error) return <p className="text-red-500">Failed to load posts: {error.message}</p>;
  
    return (
      <div className="p-4">
        <h2 className="text-xl font-bold">Posts (SWR)</h2>
        <ul>
          {data?.map((post) => (
            <li key={post.id}>
              <strong>{post.title}</strong>
            </li>
          ))}
        </ul>
      </div>
    );
  }
  

• Using React Query (TanStack Query): A powerful data-fetching library that provides robust caching, synchronization, and error handling.

  // components/PostsWithReactQuery.tsx
  'use client';
  
  import {
    useQuery,
    QueryClient,
    QueryClientProvider,
  } from '@tanstack/react-query'; // Ensure these are installed
  
  // Create a client
  const queryClient = new QueryClient();
  
  const fetchPosts = async (): Promise<Post[]> => {
    const res = await fetch('/api/posts');
    if (!res.ok) {
      throw new Error('Network response was not ok');
    }
    return res.json();
  };
  
  function PostsContent() {
    const { data, isLoading, error } = useQuery({
      queryKey: ['posts'],
      queryFn: fetchPosts,
    });
  
    if (isLoading) return <p>Loading posts with React Query...</p>;
    if (error) return <p className="text-red-500">Error: {error.message}</p>;
  
    return (
      <div className="p-4">
        <h2 className="text-xl font-bold">Posts (React Query)</h2>
        <ul>
          {data?.map((post) => (
            <li key={post.id}>
              <strong>{post.title}</strong>
            </li>
          ))}
        </ul>
      </div>
    );
  }
  
  export default function PostsWithReactQuery() {
    return (
      <QueryClientProvider client={queryClient}>
        <PostsContent />
      </QueryClientProvider>
    );
  }
  

4.3: Request Deduplication and Data Cache

Next.js automatically deduplicates fetch requests with the same URL and options within a single render pass (both on the server and client). This ensures that if multiple components on the same page request the same data, the actual network request is only made once.

For ORM or database calls, you can use React.cache to achieve similar deduplication.

Data Cache: Next.js also leverages a Data Cache. When fetch requests are made in Server Components, their responses can be cached.

• cache: 'force-cache' (default): Fetches are cached indefinitely. Useful for data that rarely changes.

• next: { revalidate: <seconds> }: Data is cached for the specified seconds. After this time, the next request will revalidate the data. This is Incremental Static Regeneration (ISR) in the App Router.

• revalidatePath(path) / revalidateTag(tag): Imperatively revalidate cached data. This is powerful for triggering updates after mutations (e.g., from Server Actions).

  // actions/products.ts
  'use server';
  
  import { revalidatePath, revalidateTag } from 'next/cache';
  
  export async function addProduct(formData: FormData) {
    const name = formData.get('name') as string;
    const price = parseFloat(formData.get('price') as string);
  
    // Save product to database
    const newProduct = { id: Date.now(), name, price }; // Simulate DB save
    // await db.products.create({ data: newProduct });
  
    // Revalidate paths or tags that display product data
    revalidatePath('/dashboard/products'); // Revalidate a specific page
    revalidateTag('products'); // Revalidate data tagged 'products'
  }
  

4.4: Incremental Static Regeneration (ISR) and Partial Prerendering (PPR)

• Incremental Static Regeneration (ISR):

  • What it is: A hybrid rendering strategy that allows you to update static content after the initial build, without rebuilding the entire site. Pages are generated at build time, then revalidated at specified intervals or on demand.
  • Why it’s important: Provides the benefits of static sites (fast initial load, low server cost) for dynamic content. Content can be updated frequently without full redeployments.
  • How it works (App Router): By using fetch with next: { revalidate: <seconds> } in a Server Component.
  • Example: See getLatestArticles example in section 4.1.

• Partial Prerendering (PPR) (Preview in Next.js 15, fully coming in Next.js 16):

  • What it is: An optimization that aims to provide the benefits of static sites with dynamic content. It generates a static HTML “shell” based on Suspense boundaries at build time, and then streams dynamic content into those “holes” at request time.

  • Why it’s important: Solves the tradeoff between static performance and dynamic freshness without extra configuration. The static shell loads instantly, improving metrics, while dynamic parts hydrate seamlessly.

  • How it works (Next.js 15+): PPR is built on React Suspense and loading.tsx. Next.js automatically prerenders the static parts of your page (outside Suspense boundaries, or the fallback of a Suspense boundary). When a request comes in, the static shell is served immediately, and the dynamic content (the parts within Suspense or that rely on dynamic data like cookies) is streamed in on the same HTTP request. No new APIs are needed beyond Suspense and loading.tsx.

  • Example (conceptual, as it’s largely an opt-in compiler optimization):

    // app/product/[id]/page.tsx
    import { Suspense } from 'react';
    import ProductReviews from '@/components/ProductReviews'; // A component that fetches dynamic reviews
    import ProductDescription from '@/components/ProductDescription'; // A component that fetches static-like description
    
    export default function ProductPage({ params }: { params: { id: string } }) {
      return (
        <div>
          <h1 className="text-3xl font-bold">Product ID: {params.id}</h1>
          {/* This part (ProductDescription) can be largely static and prerendered */}
          <ProductDescription productId={params.id} />
    
          <h2 className="text-2xl mt-8">Customer Reviews</h2>
          {/* This part (ProductReviews) will stream in dynamically */}
          <Suspense fallback={<p>Loading reviews...</p>}>
            <ProductReviews productId={params.id} />
          </Suspense>
        </div>
      );
    }
    
    // components/ProductReviews.tsx (Server Component, likely dynamic due to user-specific data or frequent changes)
    // No 'use client' means it's a Server Component by default
    export default async function ProductReviews({ productId }: { productId: string }) {
      // Simulate slow dynamic data fetch
      await new Promise(resolve => setTimeout(resolve, 2000));
      const reviews = await fetch(`https://api.example.com/products/${productId}/reviews`, { cache: 'no-store' }).then(res => res.json());
    
      return (
        <div className="border p-4 mt-4">
          <h3 className="text-xl font-bold">Actual Reviews</h3>
          <ul>
            {reviews.map((review: any) => (
              <li key={review.id}>"{review.comment}" - {review.author}</li>
            ))}
          </ul>
        </div>
      );
    }
    

    With PPR, the ProductDescription part would render instantly as a static shell, while the ProductReviews section would show “Loading reviews…” and then seamlessly stream in once its data is ready, all within a single network request.

Chapter 5: Server Actions and Mutations

Server Actions are a major feature in Next.js 15, becoming stable after being introduced as experimental in Next.js 14. They simplify data mutations and backend interactions significantly.

5.1: Introduction to Server Actions

• What it is: Asynchronous functions that run directly on the server, callable directly from your React components (both Server and Client Components). They allow you to perform server-side logic (e.g., database writes, API calls) without defining separate API routes.
• Why it was introduced: To streamline the developer experience for data mutations by removing the need for explicit API routes and simplifying client-server communication. They promote a more “full-stack React” approach.
• How it works: You mark a function with 'use server' (either in its own file or inline within an async Server Component). When called from the client, Next.js automatically handles the network request to execute that function on the server.
• Benefits:
  • Simplified Data Mutations: No separate /api routes needed for form submissions or mutations.
  • Reduced Client-Side JavaScript: Logic remains on the server.
  • Type Safety: End-to-end type safety between client and server with TypeScript.
  • Progressive Enhancement: Forms using Server Actions work even if JavaScript is disabled.
  • Deep Integration: Integrate with caching, revalidation, and redirects.

5.2: Form Handling with Server Actions

Server Actions integrate seamlessly with HTML <form> elements and React’s useActionState and useFormStatus hooks (available in React’s canary channel, which Next.js App Router utilizes).

• Simple Form Example:

  // app/add-item/page.tsx (Server Component)
  import { revalidatePath } from 'next/cache';
  
  export default function AddItemPage() {
    async function addItem(formData: FormData) {
      'use server'; // Define an inline Server Action
  
      const itemName = formData.get('itemName') as string;
  
      // Simulate saving to a database
      console.log(`Saving item: ${itemName}`);
      // await db.items.create({ data: { name: itemName } });
  
      // Revalidate the path that displays the items
      revalidatePath('/items');
    }
  
    return (
      <div className="p-4">
        <h1 className="text-2xl font-bold">Add New Item</h1>
        <form action={addItem} className="mt-4 flex gap-2">
          <input
            type="text"
            name="itemName"
            placeholder="Item name"
            required
            className="border p-2 rounded flex-grow"
          />
          <button
            type="submit"
            className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
          >
            Add Item
          </button>
        </form>
      </div>
    );
  }
  

• Form with State Management (useActionState and useFormStatus): useActionState allows you to manage the state of a form action, including errors and results. useFormStatus gives you access to the pending status of the form.

  // actions/auth.ts (dedicated Server Action file)
  'use server';
  
  import { z } from 'zod'; // For schema validation
  import { revalidatePath } from 'next/cache';
  import { redirect } from 'next/navigation';
  
  // Define a schema for validation
  const SignupSchema = z.object({
    email: z.string().email('Invalid email address.'),
    password: z.string().min(8, 'Password must be at least 8 characters.'),
  });
  
  interface FormState {
    message: string;
    errors?: {
      email?: string[];
      password?: string[];
    };
  }
  
  export async function signup(prevState: FormState, formData: FormData): Promise<FormState> {
    const validatedFields = SignupSchema.safeParse({
      email: formData.get('email'),
      password: formData.get('password'),
    });
  
    if (!validatedFields.success) {
      return {
        message: 'Validation failed.',
        errors: validatedFields.error.flatten().fieldErrors,
      };
    }
  
    const { email, password } = validatedFields.data;
  
    try {
      // Simulate user creation in a database
      // await db.user.create({ data: { email, password } });
      console.log(`User created: ${email}`);
      revalidatePath('/dashboard'); // Revalidate a dashboard displaying users
      redirect('/login'); // Redirect after successful signup
      return { message: 'Signup successful!' }; // This line won't be reached due to redirect
    } catch (error) {
      console.error('Signup error:', error);
      return { message: 'Failed to create account.' };
    }
  }
  

  // app/signup/page.tsx
  'use client'; // This page needs client-side interactivity for form hooks
  
  import { useActionState, useFormStatus } from 'react-dom'; // From React canary
  import { signup } from '@/actions/auth'; // Import your Server Action
  
  function SubmitButton() {
    const { pending } = useFormStatus();
    return (
      <button
        type="submit"
        disabled={pending}
        className="px-4 py-2 bg-green-500 text-white rounded hover:bg-green-600 disabled:bg-gray-400"
      >
        {pending ? 'Signing up...' : 'Sign Up'}
      </button>
    );
  }
  
  export default function SignupPage() {
    const [state, formAction] = useActionState(signup, { message: '' });
  
    return (
      <div className="p-4 max-w-md mx-auto">
        <h1 className="text-2xl font-bold mb-4">Create an Account</h1>
        <form action={formAction} className="space-y-4">
          <div>
            <label htmlFor="email" className="block text-sm font-medium text-gray-700">Email</label>
            <input
              type="email"
              id="email"
              name="email"
              required
              className="mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md"
            />
            {state.errors?.email && (
              <p className="text-red-500 text-sm mt-1">{state.errors.email.join(', ')}</p>
            )}
          </div>
          <div>
            <label htmlFor="password" className="block text-sm font-medium text-gray-700">Password</label>
            <input
              type="password"
              id="password"
              name="password"
              required
              className="mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md"
            />
            {state.errors?.password && (
              <p className="text-red-500 text-sm mt-1">{state.errors.password.join(', ')}</p>
            )}
          </div>
          <SubmitButton />
          {state.message && (
            <p className={`mt-2 ${state.errors ? 'text-red-500' : 'text-green-500'}`}>
              {state.message}
            </p>
          )}
        </form>
      </div>
    );
  }
  

5.3: Integrating Server Actions with Caching and Revalidation

Server Actions are deeply integrated with Next.js’s caching mechanisms. After a successful mutation, you often need to revalidate cached data so that the UI reflects the changes.

• revalidatePath(path): Invalidates the cache for a specific data path. This tells Next.js to refetch data for that path on the next request.

• revalidateTag(tag): Invalidates the cache for all fetch requests associated with a specific tag. This is useful for revalidating data across multiple pages or components that share the same data.

  // actions/comments.ts
  'use server';
  
  import { revalidatePath, revalidateTag } from 'next/cache';
  
  export async function addComment(formData: FormData) {
    const postId = formData.get('postId') as string;
    const commentText = formData.get('commentText') as string;
  
    // Simulate saving comment to DB
    console.log(`Adding comment to post ${postId}: ${commentText}`);
    // await db.comments.create({ data: { postId, text: commentText } });
  
    // Revalidate the individual post page
    revalidatePath(`/posts/${postId}`);
    // Revalidate a tag for general comments feed if one exists
    revalidateTag('comments');
  
    return { success: true };
  }
  

5.4: Security Considerations for Server Actions

While Server Actions simplify development, it’s crucial to understand their security implications:

• Authentication and Authorization:

  • Always authenticate and authorize within your Server Actions. Even though they run on the server, they can be invoked from untrusted clients. Do not rely solely on UI-level checks.
  • Example: Before performing a database write, check if the user is logged in and has the necessary permissions.

  // actions/admin.ts
  'use server';
  
  import { auth } from '@/lib/auth'; // A hypothetical auth utility to get user session
  import { db } from '@/lib/db';
  import { revalidatePath } from 'next/cache';
  
  export async function deleteUser(userId: string) {
    const session = await auth.getSession(); // Get current user session
    if (!session || !session.user || session.user.role !== 'admin') {
      throw new Error('Unauthorized: Only administrators can delete users.');
    }
  
    try {
      await db.user.delete({ where: { id: userId } });
      revalidatePath('/admin/users');
      return { success: true };
    } catch (error) {
      console.error('Failed to delete user:', error);
      return { error: 'Failed to delete user.' };
    }
  }
  

• Input Validation: Always validate incoming data from FormData or other sources. Use a validation library like Zod or Yup. This prevents malicious input from affecting your backend. (See SignupSchema example in section 5.2).

• Avoid Exposing Sensitive Data: Ensure your Server Actions (and any data fetching functions) only return necessary data to the client. Avoid sending full database records with sensitive fields if they are not needed on the frontend. Use Data Transfer Objects (DTOs) if necessary.

  // lib/user-dto.ts (Server-only file to ensure it's not bundled on client)
  import 'server-only'; // Ensures this file is only used on the server
  
  interface UserData {
    id: string;
    email: string;
    name: string;
    isAdmin: boolean;
    // ... other sensitive fields
  }
  
  interface UserProfileDTO {
    id: string;
    name: string;
    email?: string; // Optional for non-admins
  }
  
  export function toUserProfileDTO(user: UserData, viewerIsAdmin: boolean): UserProfileDTO {
    return {
      id: user.id,
      name: user.name,
      email: viewerIsAdmin ? user.email : undefined, // Only expose email if viewer is admin
    };
  }
  
  // Example Server Component using DTO
  // app/users/[id]/page.tsx
  import { prisma } from '@/lib/db';
  import { toUserProfileDTO } from '@/lib/user-dto';
  import { auth } from '@/lib/auth';
  
  export default async function PublicUserProfilePage({ params }: { params: { id: string } }) {
    const user = await prisma.user.findUnique({ where: { id: params.id } });
    if (!user) return null;
  
    const session = await auth.getSession();
    const viewerIsAdmin = session?.user?.role === 'admin';
  
    const userProfile = toUserProfileDTO(user, viewerIsAdmin);
  
    return (
      <div>
        <h1>{userProfile.name}'s Profile</h1>
        {userProfile.email && <p>Email: {userProfile.email}</p>}
        {/* ... other public profile data */}
      </div>
    );
  }
  

Chapter 6: Advanced Next.js Concepts

Beyond the core App Router features, Next.js offers several other tools and practices for building robust and performant applications.

6.1: Middleware and Edge Functions

• Middleware:

  • What it is: Code that runs before a request is completed on your site. It allows you to intercept requests and responses to modify them or apply logic (e.g., authentication, redirects, rewrites, add headers).

  • Why it’s important: Provides a powerful way to centralize logic that applies to multiple routes without duplicating code.

  • How it works: You define a middleware.ts (or .js) file at the root of your src directory or app directory. It uses the Edge Runtime for extremely fast execution.

  • Example (Authentication check and redirect):

    // middleware.ts
    import { NextResponse } from 'next/server';
    import type { NextRequest } from 'next/server';
    
    export const config = {
      matcher: ['/dashboard/:path*', '/settings/:path*'], // Routes to apply middleware
    };
    
    export function middleware(request: NextRequest) {
      const isAuthenticated = request.cookies.has('session-token');
      const url = request.nextUrl;
    
      if (!isAuthenticated && (url.pathname.startsWith('/dashboard') || url.pathname.startsWith('/settings'))) {
        // Redirect to login page if not authenticated
        return NextResponse.redirect(new URL('/login', request.url));
      }
    
      return NextResponse.next(); // Continue to the requested page
    }
    

    Pain Point/Best Practice: Middleware should NOT be your sole authentication layer for sensitive data. As highlighted by CVE-2025-29927, middleware has limitations with static routes and can be bypassed. Authentication and authorization checks should primarily reside in your Data Access Layer and Server Components (see Chapter 7). Middleware is best for:

    • Rewrites/Redirects (e.g., A/B testing, country-based routing)
    • Adding/modifying request headers
    • Stateless, optimistic checks (e.g., checking for a presence of a cookie, not its validity against a DB)
    • Geo-location based logic

• Edge Functions:

  • What it is: Serverless functions that execute at the “edge” of the network, physically closer to your users.
  • Why it’s important: Provides extremely low latency responses, ideal for personalized content, A/B tests, and dynamic routing that needs to be fast. Middleware runs as an Edge Function.
  • How it works: They are written using standard Web APIs (like Request and Response) and have a smaller runtime environment compared to Node.js functions.
  • Next.js Integration: Middleware is inherently an Edge Function. You can also create standalone Edge-compatible API routes.

6.2: Styling in Next.js (Tailwind CSS, Shadcn UI, etc.)

Next.js is unopinionated about styling, supporting various approaches:

• CSS Modules: Default for component-level CSS scoping.

  // styles/Button.module.css
  .button {
    background-color: blue;
    color: white;
    padding: 10px 20px;
    border-radius: 5px;
  }
  
  // components/MyButton.tsx
  import styles from '../styles/Button.module.css';
  
  export default function MyButton() {
    return <button className={styles.button}>Click Me</button>;
  }
  

• Global CSS: Import directly into app/layout.tsx for global styles.

  // app/globals.css
  body {
    font-family: sans-serif;
  }
  
  // app/layout.tsx
  import './globals.css';
  // ...
  

• Tailwind CSS: A utility-first CSS framework that allows rapid UI development. Highly customizable and recommended for new projects.
  • Installation: npm install -D tailwindcss postcss autoprefixer. Then npx tailwindcss init -p. Configure tailwind.config.js and import tailwind.css into globals.css.
  • Example: <button className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">Styled Button</button>
• Shadcn UI: A collection of re-usable components built with Tailwind CSS and Radix UI. You copy the component code directly into your project, giving you full control and customizability.
  • Benefit: Not a traditional component library dependency, but rather a collection of starter components you own. Highly customizable.
• Chakra UI / Material-UI (MUI) / Next UI / Ant Design: Popular component libraries with rich feature sets and theming options. They are usually client-side heavy. Integrate these within Client Components.

6.3: Optimizing Images with next/image

The next/image component automatically optimizes images, providing:

• Image resizing: Images are automatically sized for different viewports.
• Modern formats: Converts images to WebP or AVIF for smaller file sizes and better quality.
• Lazy loading: Images off-screen are loaded only when they come into view.
• Blur-up placeholders: Shows a low-resolution blur-up placeholder while the image loads.

// app/page.tsx
import Image from 'next/image';
import heroImage from '@/public/hero.jpg'; // Static import

export default function HomePage() {
  return (
    <div>
      <h1 className="text-4xl font-bold mb-6">Welcome to Our Site</h1>
      <Image
        src={heroImage} // Use static import or string for external images
        alt="Hero Image"
        width={800} // Desired width in pixels
        height={450} // Desired height in pixels
        priority // Preload this image as it's critical for LCP
        className="rounded-lg shadow-lg"
      />
      <Image
        src="https://example.com/dynamic-image.jpg" // Dynamic external image
        alt="Dynamic Image"
        width={600}
        height={400}
        sizes="(max-width: 768px) 100vw, 50vw" // Responsive sizing
        quality={75} // Image quality (0-100)
        className="mt-8 rounded-lg"
      />
    </div>
  );
}

Tips: Always define width and height (or use fill for responsiveness) to prevent Cumulative Layout Shift (CLS). Use priority for images in the initial viewport.

6.4: Font Optimization

Next.js 13+ introduced next/font for automatic font optimization, improving performance and reducing layout shifts. It self-hosts fonts, removes external network requests, and handles font loading best practices (e.g., font-display: optional).

// app/layout.tsx
import './globals.css';
import { Inter, Roboto_Mono } from 'next/font/google';

// Define fonts
const inter = Inter({ subsets: ['latin'], variable: '--font-inter' });
const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap', // Swap to fallback font immediately, then load
  variable: '--font-roboto-mono',
});

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

// In your CSS (e.g., globals.css)
:root {
  --font-inter: var(--font-inter-fallback); /* Fallback is automatically generated */
  --font-roboto-mono: var(--font-roboto-mono-fallback);
}

body {
  font-family: var(--font-inter);
}

code {
  font-family: var(--font-roboto-mono);
}

Tips: Use variable to create CSS variables for your fonts, making them easy to apply in your stylesheets.

6.5: Internationalization Enhancements

Next.js provides built-in support for internationalized (i18n) routing, which simplifies handling multiple languages.

• Configuration: Configure locales in next.config.js.

  // next.config.mjs
  /** @type {import('next').NextConfig} */
  const nextConfig = {
    experimental: {
      serverActions: true,
      // ... other experimental flags from Next.js 15.4 blog
      // cacheComponents: true, // For Next.js 16 preview
      // dynamicIO: true, // For Next.js 16 preview
    },
    i18n: {
      locales: ['en', 'fr', 'de'],
      defaultLocale: 'en',
      localeDetection: false, // Set to true if you want automatic detection
    },
  };
  
  export default nextConfig;
  

• Usage: Next.js handles routing (e.g., /fr/about for the French version of the about page). You’ll typically use a library like next-intl or react-i18next for managing translations.

Chapter 7: Authentication and Authorization

Implementing secure authentication and authorization in Next.js, especially with the App Router, requires understanding new best practices.

7.1: Modern Authentication Best Practices

The Next.js team has significantly updated its authentication recommendations due to the nuances of Server Components and a past vulnerability (CVE-2025-29927).

• Middleware is NOT for primary authentication checks for sensitive data. While it’s useful for redirects and rewrites, it should not be your single point of truth for authorization, especially for statically generated routes.
• Prioritize Data Access Layers (DAL): Centralize all data access logic, including authentication and authorization checks, as close to the data source as possible (e.g., in functions called by Server Components).
• Proximity Principle: Authentication checks should be performed where data is accessed or mutations occur (i.e., in Server Components, Server Actions, or API Routes that directly handle data).
• Server Components for Role-Based Access Control (RBAC): Leverage Server Components to conditionally render UI or restrict access based on user roles fetched securely on the server.
• Client-Side Context for UI State: Use React Context (within Client Components) for client-side authentication state (e.g., showing a login/logout button, user avatar), but not for critical authorization.

7.2: Data Access Layers for Auth Checks

A Data Access Layer (DAL) acts as a centralized point for fetching and modifying data, and critically, for enforcing authentication and authorization.

// lib/auth-dal.ts (Server-only file)
import 'server-only';
import { cache } from 'react';
import { cookies } from 'next/headers';
import { redirect } from 'next/navigation';

interface Session {
  userId: string;
  role: 'user' | 'admin';
  // ... other session data
}

// Simulate a function to validate a session token
async function validateSessionToken(token: string): Promise<Session | null> {
  // In a real app, this would verify JWT, query a database, or call an auth provider
  await new Promise(resolve => setTimeout(resolve, 100)); // Simulate async
  if (token === 'valid-admin-token') {
    return { userId: '123', role: 'admin' };
  }
  if (token === 'valid-user-token') {
    return { userId: '456', role: 'user' };
  }
  return null;
}

// Memoized function to verify session (runs once per request)
export const getSession = cache(async (): Promise<Session | null> => {
  const sessionToken = cookies().get('session-token')?.value;
  if (!sessionToken) {
    return null;
  }
  return validateSessionToken(sessionToken);
});

// Example of a data access function with authorization
export const getSensitiveUserData = cache(async (targetUserId: string) => {
  const session = await getSession();

  if (!session) {
    redirect('/login'); // Redirect if not authenticated
  }

  // Authorization check: User can only view their own data or if they are an admin
  if (session.userId !== targetUserId && session.role !== 'admin') {
    throw new Error('Unauthorized access to sensitive user data.');
  }

  // Simulate fetching data from DB
  await new Promise(resolve => setTimeout(resolve, 50));
  return {
    id: targetUserId,
    secretInfo: `Secret data for ${targetUserId} visible to ${session.role}`,
  };
});