Pages Router vs. App Router:

Next.js has evolved its architecture with the introduction of the App Router in version 13+, moving from the traditional Pages Router to a more flexible React Server Components-based approach:

// Pages Router (Traditional)
// pages/products/[id].tsx
export async function getServerSideProps(context) {
  const { id } = context.params;
  const product = await fetchProduct(id);
  return { props: { product } };
}

export default function ProductPage({ product }) {
  return 
{product.name}
;
}

// App Router (Modern)
// app/products/[id]/page.tsx
export default async function ProductPage({ params }) {
  const product = await fetchProduct(params.id);
  return 
{product.name}
;
}
        

Implementation of Different Rendering Strategies:

// Server-Side Rendering (SSR)
// Computed on every request
export async function getServerSideProps(context) {
  return {
    props: { data: await fetchData(context.params.id) }
  };
}

// Static Site Generation (SSG)
// Computed at build time
export async function getStaticProps() {
  return {
    props: { data: await fetchStaticData() }
  };
}

// Incremental Static Regeneration (ISR)
// Revalidates cached version after specified interval
export async function getStaticProps() {
  return {
    props: { data: await fetchData() },
    revalidate: 60 // seconds
  };
}
        

React Server Components in App Router:

// app/dashboard/page.tsx
// This component executes on the server
// No JS for this component is sent to the client
async function Dashboard() {
  // Direct database access - safe because this never runs on the client
  const data = await db.query("SELECT * FROM sensitive_data");
  
  return (
    

      
Dashboard
      
       {/* Only interactive components send JS to client */}
    
  );
}

// This component will be sent to the client
"use client";
function ClientSideChart() {
  const [filter, setFilter] = useState("all");
  // Client-side interactivity
  return ;
}
        

Advanced App Router Structure:

app/
  (marketing)/         # Route group (doesn't affect URL)
    about/
      page.js          # /about
    blog/
      [slug]/
        page.js        # /blog/:slug
  dashboard/
    @analytics/        # Parallel route
      page.js  
    @team/             # Parallel route
      page.js
    layout.js          # Shared layout for dashboard and its parallel routes
    page.js            # /dashboard
  api/
    webhooks/
      route.js         # API endpoint
        

Advanced Link Usage with Options:

import Link from 'next/link';

function AdvancedLinks() {
  return (
    <>
      {/* Shallow routing - update path without running data fetching methods */}
      
        Analytics
      
      
      {/* Pass href as object with query parameters */}
      
        Product Details
      
      
      {/* Scroll to specific element */}
      
        Pricing FAQ
      
    
  );
}
        

Advanced Router Usage:

import { useRouter } from 'next/router';  // Pages Router
// OR
import { useRouter } from 'next/navigation';  // App Router

function RouterEvents() {
  const router = useRouter();
  
  // Handle router events (Pages Router)
  React.useEffect(() => {
    const handleStart = (url) => {
      console.log(`Navigation to ${url} started`);
      // Start loading indicator
    };
    
    const handleComplete = (url) => {
      console.log(`Navigation to ${url} completed`);
      // Stop loading indicator
    };
    
    const handleError = (err, url) => {
      console.error(`Navigation to ${url} failed: ${err}`);
      // Handle error state
    };
    
    router.events.on('routeChangeStart', handleStart);
    router.events.on('routeChangeComplete', handleComplete);
    router.events.on('routeChangeError', handleError);
    
    return () => {
      router.events.off('routeChangeStart', handleStart);
      router.events.off('routeChangeComplete', handleComplete);
      router.events.off('routeChangeError', handleError);
    };
  }, [router]);
  
  // Advanced programmatic navigation
  const navigateWithState = () => {
    router.push({
      pathname: '/dashboard',
      query: { section: 'analytics' }
    }, undefined, { 
      shallow: true,
      scroll: false
    });
  };
  
  return (
    
      Navigate with Advanced Options
    
  );
}
        

App Router Navigation:

// In App Router navigation
import { useRouter, usePathname, useSearchParams } from 'next/navigation';

function AppRouterNavigation() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();
  
  // Create new search params
  const createQueryString = (name, value) => {
    const params = new URLSearchParams(searchParams);
    params.set(name, value);
    return params.toString();
  };
  
  // Update just the query params without full navigation
  const updateFilter = (filter) => {
    router.push(
      `${pathname}?${createQueryString('filter', filter)}`
    );
  };
  
  // Prefetch a route
  const prefetchImportantRoute = () => {
    router.prefetch('/dashboard');
  };
  
  return (
    

       updateFilter('price')}>
        Filter by Price
      
      
       router.refresh()}>
        Refresh Current Route Data
      
      
       router.back()}>
        Go Back
      
    
  );
}
        

// Static Routes
// pages/about.js → /about
export default function About() {
  return <div>About Page</div>
}

// Dynamic Routes
// pages/post/[id].js → /post/1, /post/abc, etc.
export default function Post({ id }) {
  return <div>Post: {id}</div>
}

// Catch-all Routes
// pages/blog/[...slug].js → /blog/2023/01/post
export default function BlogPost({ slug }) {
  // slug will be an array: ["2023", "01", "post"]
  return <div>Blog Path: {slug.join("/")}</div>
}

// Optional catch-all routes
// pages/[[...params]].js
export default function OptionalCatchAll({ params }) {
  // params can be undefined, or an array of path segments
  return <div>Optional params: {params ? params.join("/") : "none"}</div>
}
        

Atomic Design Hierarchy:

components/
  atoms/           // Fundamental building blocks (buttons, inputs)
    Button/
      Button.tsx
      Button.test.tsx
      Button.module.css
      index.ts     // Re-export for clean imports
  molecules/       // Combinations of atoms (form fields, search bars)
  organisms/       // Complex UI sections (navigation, forms)
  templates/       // Page layouts 
  pages/           // Page-specific components
        

Composable Component with TypeScript:

// components/atoms/Button/Button.tsx
import React, { forwardRef } from "react";
import cn from "classnames";
import styles from "./Button.module.css";

type ButtonVariant = "primary" | "secondary" | "outline";
type ButtonSize = "small" | "medium" | "large";

export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant;
  size?: ButtonSize;
  isLoading?: boolean;
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  (
    {
      children,
      className,
      variant = "primary",
      size = "medium",
      isLoading = false,
      leftIcon,
      rightIcon,
      disabled,
      ...rest
    },
    ref
  ) => {
    return (
      <button
        ref={ref}
        className={cn(
          styles.button,
          styles[variant],
          styles[size],
          isLoading && styles.loading,
          className
        )}
        disabled={disabled || isLoading}
        {...rest}
      >
        {isLoading && <span className={styles.spinner} />}
        {leftIcon && <span className={styles.leftIcon}>{leftIcon}</span>}
        <span className={styles.content}>{children}</span>
        {rightIcon && <span className={styles.rightIcon}>{rightIcon}</span>}
      </button>
    );
  }
);

Button.displayName = "Button";

export default Button;
        

Component Test Example:

// components/atoms/Button/Button.test.tsx
import { render, screen, fireEvent } from "@testing-library/react";
import Button from "./Button";

describe("Button", () => {
  it("renders correctly", () => {
    render(<Button>Click me</Button>);
    expect(screen.getByRole("button", { name: /click me/i })).toBeInTheDocument();
  });

  it("calls onClick when clicked", () => {
    const handleClick = jest.fn();
    render(<Button onClick={handleClick}>Click me</Button>);
    fireEvent.click(screen.getByRole("button"));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  it("shows loading state", () => {
    render(<Button isLoading>Click me</Button>);
    expect(screen.getByRole("button")).toHaveClass("loading");
    expect(screen.getByRole("button")).toBeDisabled();
  });
});
        

Example: styled-components with SSR

// pages/_document.js
import Document from 'next/document'
import { ServerStyleSheet } from 'styled-components'

export default class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const sheet = new ServerStyleSheet()
    const originalRenderPage = ctx.renderPage
    
    try {
      ctx.renderPage = () =>
        originalRenderPage({
          enhanceApp: (App) => (props) =>
            sheet.collectStyles(<App {...props} />),
        })
      
      const initialProps = await Document.getInitialProps(ctx)
      return {
        ...initialProps,
        styles: (
          <>
            {initialProps.styles}
            {sheet.getStyleElement()}
          </>
        ),
      }
    } finally {
      sheet.seal()
    }
  }
}
    

Advanced File Structure:

pages/
  ├── blog/
  │   ├── [slug].js             # /blog/post-1
  │   └── [date]/[slug].js      # /blog/2023-01-01/post-1
  ├── products/
  │   ├── [category]/
  │   │   └── [id].js           # /products/electronics/123
  │   └── [...slug].js          # /products/category/subcategory/product-name
  └── dashboard/
      └── [[...params]].js      # Matches /dashboard, /dashboard/settings, etc.
        

Client-Side Parameter Access:

import { useRouter } from 'next/router'

export default function ProductPage() {
  const router = useRouter()
  const { 
    id,              // For /products/[id].js
    category,        // For /products/[category]/[id].js
    slug = []        // For /products/[...slug].js (array of segments)
  } = router.query
  
  // Handling async population of router.query
  const isReady = router.isReady
  
  if (!isReady) {
    return 
  }
  
  return (
    // Component implementation
  )
}
        

Server-Side Parameter Access:

// With getServerSideProps
export async function getServerSideProps({ params, query }) {
  const { id } = params  // From the path
  const { sort } = query // From the query string
  
  // Fetch data based on parameters
  const product = await fetchProduct(id)
  
  return {
    props: { product }
  }
}

// With getStaticPaths and getStaticProps for SSG
export async function getStaticPaths() {
  const products = await fetchAllProducts()
  
  const paths = products.map((product) => ({
    params: { id: product.id.toString() }
  }))
  
  return {
    paths,
    fallback: 'blocking' // or true, or false
  }
}

export async function getStaticProps({ params }) {
  const { id } = params
  const product = await fetchProduct(id)
  
  return {
    props: { product },
    revalidate: 60 // ISR: revalidate every 60 seconds
  }
}
        

Shallow Routing Example:

// Updating URL parameters without rerunning data fetching
router.push(
  {
    pathname: '/products/[category]',
    query: { 
      category: 'electronics',
      sort: 'price-asc'
    }
  },
  undefined,
  { shallow: true }
)
        

Implementation Comparison:

// Catch-all route implementation (pages/docs/[...slug].js)
export async function getStaticPaths() {
  return {
    paths: [
      { params: { slug: ['introduction'] } },              // /docs/introduction
      { params: { slug: ['advanced', 'routing'] } },      // /docs/advanced/routing
    ],
    fallback: 'blocking'
  }
}

export async function getStaticProps({ params }) {
  const { slug } = params
  // slug is guaranteed to be an array
  const content = await fetchDocsContent(slug.join('/'))
  
  return { props: { content } }
}

// Optional catch-all route implementation (pages/docs/[[...slug]].js)
export async function getStaticPaths() {
  return {
    paths: [
      { params: { slug: [] } },                             // /docs
      { params: { slug: ['introduction'] } },             // /docs/introduction
      { params: { slug: ['advanced', 'routing'] } },     // /docs/advanced/routing
    ],
    fallback: false
  }
}

export async function getStaticProps({ params }) {
  // slug might be undefined for /docs
  const { slug = [] } = params
  
  if (slug.length === 0) {
    return { props: { content: 'Documentation Home' } }
  }
  
  const content = await fetchDocsContent(slug.join('/'))
  return { props: { content } }
}
        

Combining with API Routes:

// pages/api/[...path].js
export default function handler(req, res) {
  const { path } = req.query  // Array of path segments
  
  // Dynamic API handling based on path segments
  if (path[0] === 'users' && path.length > 1) {
    const userId = path[1]
    
    switch (req.method) {
      case 'GET':
        return handleGetUser(req, res, userId)
      case 'PUT':
        return handleUpdateUser(req, res, userId)
      // ...other methods
    }
  }
  
  res.status(404).json({ error: 'Not found' })
}
        

Leveraging Catch-all Patterns with Middleware:

// middleware.js
import { NextResponse } from 'next/server'

export function middleware(request) {
  const { pathname } = request.nextUrl
  
  // Match /docs/... paths for authorization
  if (pathname.startsWith('/docs/')) {
    const segments = pathname.slice(6).split('/'). filter(Boolean)
    
    // Check if accessing restricted docs
    if (segments.includes('internal') && !isAuthenticated(request)) {
      return NextResponse.redirect(new URL('/login', request.url))
    }
  }
  
  return NextResponse.next()
}

export const config = {
  matcher: ['/((?!api|_next|static|public|favicon.ico).*)'],
}
        

1. Basic Static Generation:

// For static pages without data dependencies
export default function StaticPage() {
  return 
}

// With data requirements
export async function getStaticProps(context: {
  params: Record;
  preview?: boolean;
  previewData?: any;
  locale?: string;
  locales?: string[];
  defaultLocale?: string;
}) {
  // Fetch data from external APIs, database, filesystem, etc.
  const data = await fetchExternalData()

  // Not found case handling
  if (!data) {
    return {
      notFound: true, // Returns 404 page
    }
  }

  return {
    props: { data }, // Will be passed to the page component as props
    revalidate: 60,  // Optional: enables ISR with 60 second regeneration
    notFound: false, // Optional: custom 404 behavior
    redirect: {      // Optional: redirect to another page
      destination: "/another-page",
      permanent: false,
    },
  }
}
        

2. Dynamic Path Static Generation:

// For pages with dynamic routes ([id].js, [slug].js, etc.)
export async function getStaticPaths(context: {
  locales?: string[];
  defaultLocale?: string;
}) {
  // Fetch all possible path parameters
  const products = await fetchAllProducts()
  
  const paths = products.map(product => ({
    params: { id: product.id.toString() },
    // Optional locale for internationalized routing
    locale: "en",
  }))
  
  return {
    paths,
    // fallback options control behavior for paths not returned by getStaticPaths
    fallback: true, // true, false, or "blocking"
  }
}

export async function getStaticProps({ params, locale, preview }) {
  // Fetch data using the parameters from the URL
  const product = await fetchProduct(params.id, locale)
  
  return {
    props: { product }
  }
}
        

Time-based Revalidation:

// pages/products/[id].tsx
import type { GetStaticProps, GetStaticPaths } from "next"

interface Product {
  id: string
  name: string
  price: number
  inventory: number
}

interface ProductPageProps {
  product: Product
  generatedAt: string
}

export const getStaticProps: GetStaticProps = async (context) => {
  const id = context.params?.id as string
  
  try {
    // Fetch latest product data
    const product = await fetchProductById(id)
    
    if (!product) {
      return { notFound: true }
    }
    
    return {
      props: {
        product,
        generatedAt: new Date().toISOString(),
      },
      // Page regeneration will be attempted at most once every 5 minutes
      // when a user visits this page after the revalidate period
      revalidate: 300,
    }
  } catch (error) {
    console.error(`Error generating product page for ${id}:`, error)
    
    // Error handling fallback
    return {
      // Last successfully generated version will continue to be served
      notFound: true,
      // Short revalidation time for error cases
      revalidate: 60,
    }
  }
}

export const getStaticPaths: GetStaticPaths = async () => {
  // Only pre-render the most critical products at build time
  const topProducts = await fetchTopProducts(100)
  
  return {
    paths: topProducts.map(product => ({ 
      params: { id: product.id.toString() }
    })),
    // Enable on-demand generation for non-prerendered products
    fallback: true, // or "blocking" depending on UX preferences
  }
}

// Component implementation...
        

On-Demand Revalidation (Next.js 12.2+):

// pages/api/revalidate.ts
import type { NextApiRequest, NextApiResponse } from "next"

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // Check for secret to confirm this is a valid request
  if (req.query.secret !== process.env.REVALIDATION_TOKEN) {
    return res.status(401).json({ message: "Invalid token" })
  }
  
  try {
    // Extract path to revalidate from request body or query
    const path = req.body.path || req.query.path
    
    if (!path) {
      return res.status(400).json({ message: "Path parameter is required" })
    }
    
    // Revalidate the specific path
    await res.revalidate(path)
    
    // Optional: Keep logs of revalidations
    console.log(`Revalidated: ${path} at ${new Date().toISOString()}`)
    
    return res.json({ revalidated: true, path })
  } catch (err) {
    // If there was an error, Next.js will continue to show the last
    // successfully generated page
    return res.status(500).send("Error revalidating")
  }
}
        

Basic API Structure:

// pages/api/products.ts
import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // Full access to Node.js runtime
  const products = fetchProductsFromDatabase() // Simulated DB call
  
  // Type-safe response
  res.status(200).json({ products })
}
        

/pages/api
  /auth
    /[...nextauth].js    # Catch-all route for NextAuth.js
  /products
    /index.js            # GET, POST /api/products
    /[id].js             # GET, PUT, DELETE /api/products/:id
    /categories/index.js # GET /api/products/categories
  /webhooks
    /stripe.js           # POST /api/webhooks/stripe
        

File: pages/api/users/[id].ts

import type { NextApiRequest, NextApiResponse } from 'next'

interface User {
  id: string;
  name: string;
  email: string;
}

interface ErrorResponse {
  message: string;
}

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { id } = req.query
  
  // Type safety for query parameters
  if (typeof id !== 'string') {
    return res.status(400).json({ message: 'Invalid ID format' })
  }
  
  try {
    // In a real app, fetch from database
    const user = await getUserById(id)
    
    if (!user) {
      return res.status(404).json({ message: `User with ID ${id} not found` })
    }
    
    return res.status(200).json(user)
  } catch (error) {
    console.error('Error fetching user:', error)
    return res.status(500).json({ message: 'Internal server error' })
  }
}

// Mock database function
async function getUserById(id: string): Promise {
  // Simulate database lookup
  return {
    id,
    name: `User ${id}`,
    email: `user${id}@example.com`
  }
}
        

File: pages/api/products/[category]/[id].ts

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { category, id } = req.query
  
  // Ensure both parameters are strings
  if (typeof category !== 'string' || typeof id !== 'string') {
    return res.status(400).json({ message: 'Invalid parameters' })
  }
  
  // Process based on multiple parameters
  res.status(200).json({
    category,
    id,
    name: `${category} product ${id}`
  })
}
        

File: pages/api/posts/[...slug].ts

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { slug } = req.query
  
  // slug will be an array of path segments
  // /api/posts/2023/01/featured -> slug = ['2023', '01', 'featured']
  
  if (!Array.isArray(slug)) {
    return res.status(400).json({ message: 'Invalid slug format' })
  }
  
  // Example: Get posts by year/month/tag
  const [year, month, tag] = slug
  
  res.status(200).json({
    params: slug,
    posts: `Posts from ${month}/${year} with tag ${tag || 'any'}`
  })
}
        

File: pages/api/articles/[[...filters]].ts

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { filters } = req.query
  
  // filters will be undefined for /api/articles
  // or an array for /api/articles/recent/technology
  
  if (filters && !Array.isArray(filters)) {
    return res.status(400).json({ message: 'Invalid filters format' })
  }
  
  if (!filters || filters.length === 0) {
    return res.status(200).json({ 
      articles: 'All articles' 
    })
  }
  
  res.status(200).json({
    filters,
    articles: `Articles filtered by ${filters.join(', ')}`
  })
}
        

Advanced JWT Implementation:

// lib/auth.ts
import { NextApiRequest } from 'next'
import { NextRequest } from 'next/server'
import jwt from 'jsonwebtoken'
import { cookies } from 'next/headers'

interface TokenPayload {
  userId: string;
  role: string;
  iat: number;
  exp: number;
}

export function generateTokens(user: any) {
  const accessToken = jwt.sign(
    { userId: user.id, role: user.role },
    process.env.JWT_ACCESS_SECRET!,
    { expiresIn: '15m' }
  )
  
  const refreshToken = jwt.sign(
    { userId: user.id },
    process.env.JWT_REFRESH_SECRET!,
    { expiresIn: '7d' }
  )
  
  return { accessToken, refreshToken }
}

export function verifyToken(token: string, secret: string): TokenPayload | null {
  try {
    return jwt.verify(token, secret) as TokenPayload
  } catch (error) {
    return null
  }
}

export function getTokenFromRequest(req: NextApiRequest | NextRequest): string | null {
  // API Routes
  if ('cookies' in req) {
    return req.cookies.get('token')?.value || null
  }
  
  // Middleware
  const cookieStore = cookies()
  return cookieStore.get('token')?.value || null
}
        

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import { verifyToken, getTokenFromRequest } from './lib/auth'

export function middleware(request: NextRequest) {
  // Protected routes pattern
  const isProtectedRoute = request.nextUrl.pathname.startsWith('/dashboard')
  const isAuthRoute = request.nextUrl.pathname.startsWith('/auth')
  
  if (isProtectedRoute) {
    const token = getTokenFromRequest(request)
    
    if (!token) {
      return NextResponse.redirect(new URL('/auth/login', request.url))
    }
    
    const payload = verifyToken(token, process.env.JWT_ACCESS_SECRET!)
    if (!payload) {
      return NextResponse.redirect(new URL('/auth/login', request.url))
    }
    
    // Add user info to headers for server components
    const requestHeaders = new Headers(request.headers)
    requestHeaders.set('x-user-id', payload.userId)
    requestHeaders.set('x-user-role', payload.role)
    
    return NextResponse.next({
      request: {
        headers: requestHeaders,
      },
    })
  }
  
  return NextResponse.next()
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'
}
        

Comprehensive Configuration with TypeScript:

// auth.ts (Next.js 13+ App Router)
import NextAuth from "next-auth";
import type { NextAuthOptions, User } from "next-auth";
import GoogleProvider from "next-auth/providers/google";
import GitHubProvider from "next-auth/providers/github";
import CredentialsProvider from "next-auth/providers/credentials";
import { PrismaAdapter } from "@auth/prisma-adapter";
import { compare } from "bcryptjs";
import prisma from "@/lib/prisma";

// Define custom session type
declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      name: string;
      email: string;
      role: string;
      permissions: string[];
    }
  }
  
  interface JWT {
    id: string;
    role: string;
    permissions: string[];
  }
}

export const authOptions: NextAuthOptions = {
  adapter: PrismaAdapter(prisma),
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      // Request additional scopes
      authorization: {
        params: {
          prompt: "consent",
          access_type: "offline",
          response_type: "code",
          scope: "openid email profile"
        }
      }
    }),
    GitHubProvider({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!,
      // Custom profile function to map GitHub profile data
      profile(profile) {
        return {
          id: profile.id.toString(),
          name: profile.name || profile.login,
          email: profile.email,
          image: profile.avatar_url,
          role: "user"
        }
      }
    }),
    CredentialsProvider({
      name: "Credentials",
      credentials: {
        email: { label: "Email", type: "email" },
        password: { label: "Password", type: "password" }
      },
      async authorize(credentials) {
        if (!credentials?.email || !credentials?.password) {
          return null;
        }

        const user = await prisma.user.findUnique({
          where: { email: credentials.email },
          include: {
            permissions: true
          }
        });

        if (!user || !user.password) {
          return null;
        }

        const isPasswordValid = await compare(credentials.password, user.password);
        
        if (!isPasswordValid) {
          return null;
        }

        return {
          id: user.id,
          name: user.name,
          email: user.email,
          role: user.role,
          permissions: user.permissions.map(p => p.name)
        };
      }
    })
  ],
  pages: {
    signIn: "/auth/signin",
    signOut: "/auth/signout",
    error: "/auth/error",
    verifyRequest: "/auth/verify-request",
    newUser: "/auth/new-user"
  },
  session: {
    strategy: "jwt",
    maxAge: 30 * 24 * 60 * 60, // 30 days
    updateAge: 24 * 60 * 60 // 24 hours
  },
  jwt: {
    secret: process.env.JWT_SECRET,
    // Custom encoding/decoding functions if needed
    encode: async ({ secret, token, maxAge }) => { /* custom logic */ },
    decode: async ({ secret, token }) => { /* custom logic */ }
  },
  callbacks: {
    async signIn({ user, account, profile, email, credentials }) {
      // Custom sign-in validation
      const isAllowedToSignIn = await checkUserAllowed(user.email);
      if (isAllowedToSignIn) {
        return true;
      } else {
        return false; // Return false to display error
      }
    },
    async redirect({ url, baseUrl }) {
      // Custom redirect logic
      if (url.startsWith(baseUrl)) return url;
      if (url.startsWith("/")) return new URL(url, baseUrl).toString();
      return baseUrl;
    },
    async jwt({ token, user, account, profile }) {
      // Add custom claims to JWT
      if (user) {
        token.id = user.id;
        token.role = user.role;
        token.permissions = user.permissions;
      }
      
      // Add access token from provider if needed
      if (account) {
        token.accessToken = account.access_token;
        token.provider = account.provider;
      }
      
      return token;
    },
    async session({ session, token }) {
      // Add properties to the session from token
      if (token) {
        session.user.id = token.id as string;
        session.user.role = token.role as string;
        session.user.permissions = token.permissions as string[];
      }
      return session;
    }
  },
  events: {
    async signIn({ user, account, profile, isNewUser }) {
      // Log authentication events
      await prisma.authEvent.create({
        data: {
          userId: user.id,
          type: "signIn",
          provider: account?.provider,
          ip: getIpAddress(),
          userAgent: getUserAgent()
        }
      });
    },
    async signOut({ token }) {
      // Handle sign out actions
    },
    async createUser({ user }) {
      // Additional actions when user is created
    },
    async updateUser({ user }) {
      // Additional actions when user is updated
    },
    async linkAccount({ user, account, profile }) {
      // Actions when an account is linked
    },
    async session({ session, token }) {
      // Session is updated
    }
  },
  debug: process.env.NODE_ENV === "development",
  logger: {
    error(code, ...message) {
      console.error(code, message);
    },
    warn(code, ...message) {
      console.warn(code, message);
    },
    debug(code, ...message) {
      if (process.env.NODE_ENV === "development") {
        console.debug(code, message);
      }
    }
  },
  theme: {
    colorScheme: "auto", // "auto" | "dark" | "light"
    brandColor: "#3B82F6", // Tailwind blue-500
    logo: "/logo.png",
    buttonText: "#ffffff"
  }
};

export const { handlers, auth, signIn, signOut } = NextAuth(authOptions);

// Helper functions
async function checkUserAllowed(email: string | null | undefined) {
  if (!email) return false;
  // Check against allow list or perform other validation
  return true;
}

function getIpAddress() {
  // Implementation to get IP address
  return "127.0.0.1";
}

function getUserAgent() {
  // Implementation to get user agent
  return "test-agent";
}
        

Middleware-based Protection (Next.js 13+):

// middleware.ts (App Router)
import { NextResponse } from "next/server";
import { NextRequest } from "next/server";
import { auth } from "./auth";

export async function middleware(request: NextRequest) {
  const session = await auth();
  
  // Path protection patterns
  const isAuthRoute = request.nextUrl.pathname.startsWith("/auth");
  const isApiRoute = request.nextUrl.pathname.startsWith("/api");
  const isProtectedRoute = request.nextUrl.pathname.startsWith("/dashboard") || 
                           request.nextUrl.pathname.startsWith("/admin");
  const isAdminRoute = request.nextUrl.pathname.startsWith("/admin");
  
  // Public routes - allow access
  if (!isProtectedRoute) {
    return NextResponse.next();
  }
  
  // Not authenticated - redirect to login
  if (!session) {
    const url = new URL(`/auth/signin`, request.url);
    url.searchParams.set("callbackUrl", request.nextUrl.pathname);
    return NextResponse.redirect(url);
  }
  
  // Role-based access control
  if (isAdminRoute && session.user.role !== "admin") {
    return NextResponse.redirect(new URL("/unauthorized", request.url));
  }
  
  // Add session info to headers for server components to use
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set("x-user-id", session.user.id);
  requestHeaders.set("x-user-role", session.user.role);
  
  return NextResponse.next({
    request: {
      headers: requestHeaders,
    },
  });
}

export const config = {
  matcher: [
    /*
     * Match all paths except for:
     * 1. /api/auth (NextAuth.js API routes)
     * 2. /_next (Next.js internals)
     * 3. /static (public files)
     * 4. All files in the public folder
     */
    "/((?!api/auth|_next|static|favicon.ico|.*\\.(?:jpg|jpeg|png|svg|webp)).*)",
  ],
};
        

Server Component Protection (App Router):

// app/dashboard/page.tsx
import { redirect } from "next/navigation";
import { auth } from "@/auth";

export default async function DashboardPage() {
  const session = await auth();
  
  if (!session) {
    redirect("/auth/signin?callbackUrl=/dashboard");
  }
  
  // Permission-based component rendering
  const canViewSensitiveData = session.user.permissions.includes("view_sensitive_data");
  
  return (
    

      
Dashboard
      
Welcome {session.user.name}
      
      {/* Conditional rendering based on permissions */}
      {canViewSensitiveData ? (
        
      ) : null}
    
  );
}
        

Prisma Schema:

// schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model Account {
  id                 String  @id @default(cuid())
  userId             String
  type               String
  provider           String
  providerAccountId  String
  refresh_token      String?  @db.Text
  access_token       String?  @db.Text
  expires_at         Int?
  token_type         String?
  scope              String?
  id_token           String?  @db.Text
  session_state      String?

  user User @relation(fields: [userId], references: [id], onDelete: Cascade)

  @@unique([provider, providerAccountId])
}

model Session {
  id           String   @id @default(cuid())
  sessionToken String   @unique
  userId       String
  expires      DateTime
  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
}

model User {
  id            String    @id @default(cuid())
  name          String?
  email         String?   @unique
  emailVerified DateTime?
  password      String?
  image         String?
  role          String    @default("user")
  accounts      Account[]
  sessions      Session[]
  permissions   Permission[]
  authEvents    AuthEvent[]
}

model VerificationToken {
  identifier String
  token      String   @unique
  expires    DateTime

  @@unique([identifier, token])
}

model Permission {
  id    String @id @default(cuid())
  name  String @unique
  users User[]
}

model AuthEvent {
  id        String   @id @default(cuid())
  userId    String
  type      String
  provider  String?
  ip        String?
  userAgent String?
  createdAt DateTime @default(now())
  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
}
        

Custom Credentials Provider with Rate Limiting:

// Enhanced Credentials Provider with rate limiting
import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

// Create Redis client for rate limiting
const redis = new Redis({
  url: process.env.UPSTASH_REDIS_URL!,
  token: process.env.UPSTASH_REDIS_TOKEN!,
});

// Create rate limiter that allows 5 login attempts per minute
const loginRateLimiter = new Ratelimit({
  redis,
  limiter: Ratelimit.slidingWindow(5, "1m"),
});

CredentialsProvider({
  name: "Credentials",
  credentials: {
    email: { label: "Email", type: "email" },
    password: { label: "Password", type: "password" }
  },
  async authorize(credentials, req) {
    // Check for required credentials
    if (!credentials?.email || !credentials?.password) {
      throw new Error("Email and password required");
    }
    
    // Apply rate limiting
    const ip = req.headers?.["x-forwarded-for"] || "127.0.0.1";
    const { success, limit, reset, remaining } = await loginRateLimiter.limit(
      `login_${ip}_${credentials.email.toLowerCase()}`
    );
    
    if (!success) {
      throw new Error(`Too many login attempts. Try again in ${Math.ceil((reset - Date.now()) / 1000)} seconds.`);
    }
    
    // Look up user
    const user = await prisma.user.findUnique({
      where: { email: credentials.email.toLowerCase() },
      include: {
        permissions: true
      }
    });
    
    if (!user || !user.password) {
      // Do not reveal which part of the credentials was wrong
      throw new Error("Invalid credentials");
    }
    
    // Verify password with timing-safe comparison
    const isPasswordValid = await compare(credentials.password, user.password);
    
    if (!isPasswordValid) {
      throw new Error("Invalid credentials");
    }
    
    // Check if email is verified (if required)
    if (process.env.REQUIRE_EMAIL_VERIFICATION === "true" && !user.emailVerified) {
      throw new Error("Please verify your email before signing in");
    }
    
    // Log successful authentication
    await prisma.authEvent.create({
      data: {
        userId: user.id,
        type: "signIn",
        provider: "credentials",
        ip: String(ip),
        userAgent: req.headers?.["user-agent"] || ""
      }
    });
    
    // Return user data
    return {
      id: user.id,
      name: user.name,
      email: user.email,
      role: user.role,
      permissions: user.permissions.map(p => p.name)
    };
  }
}),
        

Integration Test for Authentication:

// __tests__/auth.test.ts
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { SessionProvider } from "next-auth/react";
import { signIn } from "next-auth/react";
import LoginPage from "@/app/auth/signin/page";

// Mock next/router
jest.mock("next/navigation", () => ({
  useRouter() {
    return {
      push: jest.fn(),
      replace: jest.fn(),
      prefetch: jest.fn()
    };
  }
}));

// Mock next-auth
jest.mock("next-auth/react", () => ({
  signIn: jest.fn(),
  useSession: jest.fn(() => ({ data: null, status: "unauthenticated" }))
}));

describe("Authentication Flow", () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it("should handle credential sign in", async () => {
    // Mock successful sign in
    (signIn as jest.Mock).mockResolvedValueOnce({
      ok: true,
      error: null
    });

    render(
      
        
      
    );

    // Fill login form
    await userEvent.type(screen.getByLabelText(/email/i), "test@example.com");
    await userEvent.type(screen.getByLabelText(/password/i), "password123");
    
    // Submit form
    await userEvent.click(screen.getByRole("button", { name: /sign in/i }));

    // Verify signIn was called with correct parameters
    await waitFor(() => {
      expect(signIn).toHaveBeenCalledWith("credentials", {
        redirect: false,
        email: "test@example.com",
        password: "password123",
        callbackUrl: "/"
      });
    });
  });

  it("should display error messages", async () => {
    // Mock failed sign in
    (signIn as jest.Mock).mockResolvedValueOnce({
      ok: false,
      error: "Invalid credentials"
    });

    render(
      
        
      
    );

    // Fill and submit form
    await userEvent.type(screen.getByLabelText(/email/i), "test@example.com");
    await userEvent.type(screen.getByLabelText(/password/i), "wrong");
    await userEvent.click(screen.getByRole("button", { name: /sign in/i }));

    // Check error is displayed
    await waitFor(() => {
      expect(screen.getByText(/invalid credentials/i)).toBeInTheDocument();
    });
  });
});
        

Advanced Configuration:

import useSWR, { SWRConfig } from 'swr'

function Application() {
  return (
    <SWRConfig 
      value={{
        fetcher: (resource, init) => fetch(resource, init).then(res => res.json()),
        revalidateIfStale: true,
        revalidateOnFocus: false,
        revalidateOnReconnect: true,
        refreshInterval: 3000,
        dedupingInterval: 2000,
        focusThrottleInterval: 5000,
        errorRetryInterval: 5000,
        errorRetryCount: 3,
        suspense: false
      }}
    >
      <Component />
    </SWRConfig>
  )
}
        

┌─────────────────┐
│ Initial Request │
└────────┬────────┘
         ▼
┌──────────────────────┐    ┌─────────────────┐
│ Return Cached Value  │───▶│ Trigger Fetch   │
│ (if available)       │    │ (revalidation)  │
└──────────────────────┘    └────────┬────────┘
                                     │
         ┌──────────────────────────┘
         ▼
┌──────────────────────┐    ┌─────────────────┐
│ Deduplicate Requests │───▶│ Network Request │
└──────────────────────┘    └────────┬────────┘
                                     │
         ┌──────────────────────────┘
         ▼
┌──────────────────────┐
│ Update Cache & UI    │
└──────────────────────┘
        

Dependent Data Fetching:

// Sequential requests with dependencies
function UserPosts() {
  const { data: user } = useSWR('/api/user')
  const { data: posts } = useSWR(() => user ? `/api/posts?userId=${user.id}` : null)
  
  // posts will only start fetching when user data is available
}
        

Optimistic UI Updates:

function TodoList() {
  const { data, mutate } = useSWR('/api/todos')
  
  async function addTodo(text) {
    // Immediately update the local data (optimistic UI)
    const newTodo = { id: Date.now(), text, completed: false }
    
    // Update the cache and rerender with the new todo immediately
    mutate(async (todos) => {
      // Optimistic update
      const optimisticData = [...todos, newTodo]
      
      // Send the actual request
      await fetch('/api/todos', {
        method: 'POST',
        body: JSON.stringify(newTodo)
      })
      
      // Return the optimistic data
      return optimisticData
    }, {
      // Don't revalidate after mutation to avoid UI flickering
      revalidate: false
    })
  }
}
        

Advanced Client Component Implementation:

// components/DynamicDataComponent.js
"use client"

import { useState, useEffect, useTransition } from 'react'
import { useRouter } from 'next/navigation'

export default function DynamicDataComponent({ initialData }) {
  const router = useRouter()
  const [data, setData] = useState(initialData)
  const [isPending, startTransition] = useTransition()
  
  // Client-side data fetching with suspense transitions
  const refreshData = async () => {
    startTransition(async () => {
      const res = await fetch('api/data?timestamp=${Date.now()}')
      const newData = await res.json()
      setData(newData)
      
      // Update the URL without full navigation
      router.push(`?updated=${Date.now()}`, { scroll: false })
    })
  }
  
  // Setup polling or websocket connections
  useEffect(() => {
    const eventSource = new EventSource('/api/events')
    
    eventSource.onmessage = (event) => {
      const eventData = JSON.parse(event.data)
      setData(current => ({...current, ...eventData}))
    }
    
    return () => eventSource.close()
  }, [])
  
  return (
    <div className={isPending ? "loading-state" : ""}>
      {/* Complex interactive UI with client-side state */}
      {isPending && <div className="loading-overlay">Updating...</div>}
      {/* ... */}
      <button onClick={refreshData}>Refresh</button>
    </div>
  )
}
        

Code-Splitting with Dynamic Imports:

// Using dynamic imports for large client components
import dynamic from 'next/dynamic'

// Only load heavy components when needed
const ComplexDataVisualization = dynamic(
  () => import('../components/ComplexDataVisualization'),
  { 
    loading: () => <p>Loading visualization...</p>,
    ssr: false // Disable Server-Side Rendering completely
  }
)

// Server Component wrapper
export default function DataPage() {
  return (
    <div>
      <h1>Data Dashboard</h1>
      {/* Only loaded client-side */}
      <ComplexDataVisualization />
    </div>
  )
}
        

// app/dashboard/layout.js
import { Suspense } from 'react'
import StaticHeader from '../components/StaticHeader' // Server Component 
import MainContent from '../components/MainContent'   // Server Component
import DynamicSidebar from '../components/DynamicSidebar' // Client Component

export default function DashboardLayout({ children }) {
  return (
    <>
      <StaticHeader />
      
      <div className="dashboard-layout">
        {/* Critical content hydrated first */}
        {children}
        
        {/* Non-critical UI deferred */}
        <Suspense fallback={<div>Loading sidebar...</div>}>
          <DynamicSidebar />
        </Suspense>
        
        {/* Lowest priority components */}
        <Suspense fallback={null}>
          <MainContent />
        </Suspense>
      </div>
    </>
  )
}