Advanced

// app/products/[id]/page.tsx

// => generateStaticParams runs at build time
// => Returns array of params to pre-render
export async function generateStaticParams() {
  // => Fetch all product IDs from database/API
  const products = await fetch('https://api.example.com/products').then(res =>
    res.json()
  );
  // => products is [{ id: "1" }, { id: "2" }, { id: "3" }]

  // => Return array of params objects
  return products.map((product: any) => ({
    id: product.id.toString(),              // => Must return { id: string }
  }));
  // => Next.js pre-renders /products/1, /products/2, /products/3
}

// => Page component receives params
export default async function ProductPage({
  params,
}: {
  params: { id: string };
}) {
  // => For pre-rendered routes, this runs at build time
  // => For dynamic routes (not in generateStaticParams), runs at request time
  const product = await fetch(`https://api.example.com/products/${params.id}`).then(
    res => res.json()
  );
  // => product is { id: "1", name: "Murabaha", description: "..." }

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
    </div>
  );
}

// => Optional: enable static export (fully static site)
export const dynamicParams = false;
// => dynamicParams = false: 404 for routes not in generateStaticParams
// => dynamicParams = true (default): generate on-demand for new routes

// app/blog/[slug]/page.tsx

// => Pre-render blog posts at build time
export async function generateStaticParams() {
  const posts = await fetch('https://cms.example.com/posts').then(res =>
    res.json()
  );

  return posts.map((post: any) => ({
    slug: post.slug,
  }));
}

// => Page with ISR configuration
export default async function BlogPostPage({
  params,
}: {
  params: { slug: string };
}) {
  // => Fetch post data
  const post = await fetch(`https://cms.example.com/posts/${params.slug}`, {
    next: { revalidate: 300 },              // => Revalidate every 5 minutes
  }).then(res => res.json());
  // => First request after 5 minutes: serves stale, regenerates in background
  // => Subsequent requests: serves newly generated version

  return (
    <article>
      <h1>{post.title}</h1>
      <time>{new Date(post.publishedAt).toLocaleDateString()}</time>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

// => Alternative: page-level revalidation
export const revalidate = 300;              // => 5 minutes
// => All fetches in this page inherit this revalidate value

// => Alternative: on-demand revalidation in CMS webhook
// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  // => Webhook from CMS when post updated
  const body = await request.json();
  const slug = body.slug;                   // => slug is "zakat-guide"

  // => Verify webhook secret (security)
  const secret = request.headers.get('x-webhook-secret');
  if (secret !== process.env.WEBHOOK_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // => Revalidate specific post
  revalidatePath(`/blog/${slug}`);
  // => Regenerates page immediately, no waiting for revalidate timer

  return NextResponse.json({ revalidated: true });
}

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',                         // => Enable static export
  // => Generates static HTML/CSS/JS files in 'out' directory

  // => Optional: configure trailing slashes
  trailingSlash: true,
  // => /about → /about/index.html (better for some CDNs)

  // => Optional: configure base path
  // basePath: '/blog',
  // => All routes prefixed with /blog (e.g., /blog/posts/1)
};

module.exports = nextConfig;

// app/page.tsx
// => Static page (no server-side features)
export default function HomePage() {
  return (
    <div>
      <h1>Static Site</h1>
      <p>This page is fully static, no server required.</p>
    </div>
  );
}

// app/posts/[id]/page.tsx
// => Dynamic route with generateStaticParams
export async function generateStaticParams() {
  return [
    { id: '1' },
    { id: '2' },
    { id: '3' },
  ];
}

// => MUST set dynamicParams = false for static export
export const dynamicParams = false;
// => Without this, build fails (can't generate unknown routes)

export default function PostPage({
  params,
}: {
  params: { id: string };
}) {
  return (
    <div>
      <h1>Post {params.id}</h1>
    </div>
  );
}

// Build command:
// npm run build
// => Generates 'out' directory with static files
// => Deploy 'out' to any CDN (Cloudflare, Vercel, Netlify, S3, etc.)

// app/dashboard/page.tsx
import { Suspense } from 'react';

// => Fast component (renders immediately)
function QuickStats() {
  return (
    <div>
      <h2>Quick Stats</h2>
      <p>Last login: {new Date().toLocaleTimeString()}</p>
    </div>
  );
}

// => Slow component (async data fetch)
async function RecentDonations() {
  // => Simulate slow database query
  await new Promise(resolve => setTimeout(resolve, 3000)); // => 3 second delay

  const donations = [
    { id: 1, amount: 100000, date: '2026-01-20' },
    { id: 2, amount: 250000, date: '2026-01-25' },
  ];

  return (
    <div>
      <h2>Recent Donations</h2>
      <ul>
        {donations.map(d => (
          <li key={d.id}>
            IDR {d.amount.toLocaleString()} - {d.date}
          </li>
        ))}
      </ul>
    </div>
  );
}

// => Another slow component
async function AnalyticsChart() {
  await new Promise(resolve => setTimeout(resolve, 2000)); // => 2 second delay

  return (
    <div>
      <h2>Analytics</h2>
      <p>Total donations this month: IDR 350,000</p>
    </div>
  );
}

export default function DashboardPage() {
  return (
    <div>
      <h1>Dashboard</h1>

      {/* => Fast content renders immediately */}
      <QuickStats />

      {/* => Suspense boundary for slow content */}
      <Suspense fallback={<p>Loading donations...</p>}>
        {/* => Shows fallback while RecentDonations loads */}
        <RecentDonations />
        {/* => Replaced with actual content when ready */}
      </Suspense>

      {/* => Separate Suspense boundary (independent loading) */}
      <Suspense fallback={<p>Loading analytics...</p>}>
        <AnalyticsChart />
        {/* => Loads independently from donations */}
      </Suspense>
    </div>
  );
}
// => HTML streamed in chunks:
// => 1. Initial HTML with QuickStats + fallbacks (instant)
// => 2. AnalyticsChart HTML streamed after 2 seconds
// => 3. RecentDonations HTML streamed after 3 seconds

// app/posts/[id]/page.tsx
import { Suspense } from 'react';

// => Post header (fast)
async function PostHeader({ id }: { id: string }) {
  // => Quick database query (indexed)
  await new Promise(resolve => setTimeout(resolve, 500)); // => 0.5s

  return (
    <header>
      <h1>Post {id}</h1>
      <p>By Author Name</p>
    </header>
  );
}

// => Post content (slower)
async function PostContent({ id }: { id: string }) {
  await new Promise(resolve => setTimeout(resolve, 1500)); // => 1.5s

  return (
    <article>
      <p>This is the post content. It takes longer to load because it's large.</p>
    </article>
  );
}

// => Comments (slowest)
async function PostComments({ id }: { id: string }) {
  await new Promise(resolve => setTimeout(resolve, 3000)); // => 3s

  const comments = [
    { id: 1, author: 'Ahmad', text: 'Great post!' },
    { id: 2, author: 'Fatima', text: 'Very helpful.' },
  ];

  return (
    <section>
      <h2>Comments</h2>
      <ul>
        {comments.map(c => (
          <li key={c.id}>
            <strong>{c.author}</strong>: {c.text}
          </li>
        ))}
      </ul>
    </section>
  );
}

export default function PostPage({
  params,
}: {
  params: { id: string };
}) {
  return (
    <div>
      {/* => Outer Suspense: page structure */}
      <Suspense fallback={<div>Loading post...</div>}>
        {/* => Header loads first (0.5s) */}
        <PostHeader id={params.id} />

        {/* => Inner Suspense: content section */}
        <Suspense fallback={<p>Loading content...</p>}>
          <PostContent id={params.id} />
          {/* => Content streams after 1.5s */}
        </Suspense>

        {/* => Inner Suspense: comments section */}
        <Suspense fallback={<p>Loading comments...</p>}>
          <PostComments id={params.id} />
          {/* => Comments stream after 3s */}
        </Suspense>
      </Suspense>
    </div>
  );
}
// => Progressive loading timeline:
// => 0ms: "Loading post..." shown
// => 500ms: Header + "Loading content..." + "Loading comments..."
// => 1500ms: Header + Content + "Loading comments..."
// => 3000ms: Header + Content + Comments (fully loaded)

// app/components/Skeleton.tsx
// => Reusable skeleton components
export function SkeletonCard() {
  return (
    <div
      style={{
        background: '#e0e0e0',
        borderRadius: '8px',
        padding: '1rem',
        animation: 'pulse 1.5s ease-in-out infinite',
      }}
    >
      <div
        style={{
          height: '1.5rem',
          background: '#d0d0d0',
          borderRadius: '4px',
          marginBottom: '0.5rem',
        }}
      />
      <div
        style={{
          height: '4rem',
          background: '#d0d0d0',
          borderRadius: '4px',
        }}
      />
    </div>
  );
}

export function SkeletonList({ count = 3 }: { count?: number }) {
  return (
    <div>
      {Array.from({ length: count }).map((_, i) => (
        <div
          key={i}
          style={{
            height: '3rem',
            background: '#e0e0e0',
            borderRadius: '4px',
            marginBottom: '0.5rem',
            animation: 'pulse 1.5s ease-in-out infinite',
          }}
        />
      ))}
    </div>
  );
}

// app/posts/page.tsx
import { Suspense } from 'react';
import { SkeletonList } from '../components/Skeleton';

async function PostList() {
  await new Promise(resolve => setTimeout(resolve, 2000));

  const posts = [
    { id: 1, title: 'Zakat Guide' },
    { id: 2, title: 'Murabaha Basics' },
    { id: 3, title: 'Islamic Finance 101' },
  ];

  return (
    <ul>
      {posts.map(post => (
        <li
          key={post.id}
          style={{
            padding: '1rem',
            border: '1px solid #ddd',
            borderRadius: '4px',
            marginBottom: '0.5rem',
          }}
        >
          <h3>{post.title}</h3>
          <p>Published on Jan 29, 2026</p>
        </li>
      ))}
    </ul>
  );
}

export default function PostsPage() {
  return (
    <div>
      <h1>Blog Posts</h1>

      {/* => Suspense with skeleton fallback */}
      <Suspense fallback={<SkeletonList count={3} />}>
        {/* => Shows 3 skeleton cards while loading */}
        <PostList />
        {/* => Replaced with actual posts after 2s */}
      </Suspense>
    </div>
  );
}

// => Add CSS for pulse animation (global.css)
// @keyframes pulse {
//   0%, 100% { opacity: 1; }
//   50% { opacity: 0.5; }
// }

// app/lib/cache.ts
import { unstable_cache } from 'next/cache';
// => Import Next.js cache function

// => Expensive calculation function
async function calculateZakatRates() {
  console.log('Calculating zakat rates (expensive operation)...');

  // => Simulate expensive computation
  await new Promise(resolve => setTimeout(resolve, 2000)); // => 2 second delay

  // => Fetch gold/silver prices from external API
  const goldPrice = 950000;                 // => IDR per gram
  const silverPrice = 12000;                // => IDR per gram

  return {
    goldNisab: 85 * goldPrice,              // => 80,750,000 IDR
    silverNisab: 595 * silverPrice,         // => 7,140,000 IDR
    zakatRate: 0.025,                       // => 2.5%
  };
}

// => Cached version of calculateZakatRates
export const getZakatRates = unstable_cache(
  calculateZakatRates,                      // => Function to cache
  ['zakat-rates'],                          // => Cache key
  {
    revalidate: 3600,                       // => Revalidate every 1 hour
    tags: ['zakat', 'rates'],               // => Cache tags for revalidation
  }
);
// => First call: runs calculateZakatRates, caches result
// => Subsequent calls within 1 hour: returns cached result (instant)

// app/zakat/page.tsx
import { getZakatRates } from '../lib/cache';

export default async function ZakatPage() {
  // => Use cached function
  const rates = await getZakatRates();
  // => First request: 2 second delay
  // => Subsequent requests: instant (cached)

  return (
    <div>
      <h1>Zakat Calculator</h1>
      <p>Gold Nisab: IDR {rates.goldNisab.toLocaleString()}</p>
      <p>Silver Nisab: IDR {rates.silverNisab.toLocaleString()}</p>
      <p>Zakat Rate: {rates.zakatRate * 100}%</p>
    </div>
  );
}

// app/actions.ts
'use server';

import { revalidateTag } from 'next/cache';

export async function updateGoldPrice() {
  // => Update gold price in database
  // await db.prices.update({ ... });

  // => Invalidate zakat rates cache
  revalidateTag('rates');
  // => Next getZakatRates() call recalculates
}

// app/lib/data.ts
import { cache } from 'react';
// => Import React cache function

// => Expensive database query
async function getUserFromDB(userId: string) {
  console.log(`Database query for user ${userId}`);
  // => This log helps verify deduplication

  // => Simulate database query
  await new Promise(resolve => setTimeout(resolve, 100));

  return {
    id: userId,
    name: 'Ahmad',
    email: 'ahmad@example.com',
  };
}

// => Memoized version (deduplicates within request)
export const getUser = cache(getUserFromDB);
// => Multiple calls with same userId in single request: only one database query
// => Different requests: cache doesn't persist (new query)

// app/components/UserProfile.tsx
import { getUser } from '../lib/data';

export async function UserProfile({ userId }: { userId: string }) {
  const user = await getUser(userId);       // => Call 1: database query
  // => user is { id: "1", name: "Ahmad", ... }

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}

// app/components/UserStats.tsx
import { getUser } from '../lib/data';

export async function UserStats({ userId }: { userId: string }) {
  const user = await getUser(userId);       // => Call 2: uses cached result (same request)
  // => No database query, instant return

  return (
    <div>
      <p>User ID: {user.id}</p>
    </div>
  );
}

// app/users/[id]/page.tsx
import { UserProfile } from '@/app/components/UserProfile';
import { UserStats } from '@/app/components/UserStats';

export default function UserPage({
  params,
}: {
  params: { id: string };
}) {
  return (
    <div>
      <h1>User Details</h1>

      {/* => Both components call getUser(params.id) */}
      <UserProfile userId={params.id} />
      {/* => Triggers database query */}

      <UserStats userId={params.id} />
      {/* => Uses memoized result, no second query */}
    </div>
  );
}
// => Single request: only ONE database query despite two getUser() calls
// => Next request: cache cleared, new database query

// app/profile/page.tsx
// => Force dynamic rendering (SSR on every request)
export const dynamic = 'force-dynamic';
// => Opts out of static generation
// => Page rendered on every request (Server-Side Rendering)

import { cookies } from 'next/headers';

export default async function ProfilePage() {
  // => Read cookies (requires dynamic rendering)
  const cookieStore = cookies();
  const authToken = cookieStore.get('auth_token');

  if (!authToken) {
    return <p>Please log in.</p>;
  }

  // => Fetch user-specific data
  const user = { name: 'Ahmad', lastLogin: new Date() };

  return (
    <div>
      <h1>Your Profile</h1>
      <p>Name: {user.name}</p>
      <p>Last login: {user.lastLogin.toLocaleString()}</p>
      {/* => Always shows current time (dynamic) */}
    </div>
  );
}

// Alternative: force-static for edge cases
// export const dynamic = 'force-static';
// => Forces static generation even if cookies/headers used (throws error if incompatible)

// Alternative: auto (default)
// export const dynamic = 'auto';
// => Next.js decides based on API usage (cookies/headers = dynamic, else static)

// app/gallery/page.tsx
import Image from 'next/image';

// => Import images statically for automatic blur generation
import mosqueImage from './mosque.jpg';
// => Next.js automatically generates blur data URL at build time

export default function GalleryPage() {
  return (
    <div>
      <h1>Islamic Architecture Gallery</h1>

      {/* => Static import with automatic blur */}
      <Image
        src={mosqueImage}
        // => Static import, Next.js knows dimensions automatically

        alt="Beautiful mosque with Islamic architecture"

        placeholder="blur"
        // => Shows blur placeholder while loading
        // => blur data generated automatically from mosqueImage
      />

      {/* => Dynamic image with custom blur data URL */}
      <Image
        src="https://example.com/remote-image.jpg"
        alt="Remote Islamic art"

        width={800}
        height={600}

        placeholder="blur"
        blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
        // => Custom blur data URL (generate with tools like plaiceholder)
        // => Shows this blurred version while full image loads
      />

      {/* => Multiple images with priority */}
      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '1rem' }}>
        {[1, 2, 3].map(id => (
          <div key={id} style={{ position: 'relative', aspectRatio: '16/9' }}>
            <Image
              src={`/gallery/image-${id}.jpg`}
              alt={`Gallery image ${id}`}
              fill
              sizes="(max-width: 768px) 100vw, 33vw"
              // => Tells Next.js image sizes for responsive optimization
              // => Mobile: 100% viewport width
              // => Desktop: 33% viewport width (3 columns)
            />
          </div>
        ))}
      </div>
    </div>
  );
}

// app/layout.tsx
import { Inter, Amiri } from 'next/font/google';
// => Import Google Fonts (self-hosted automatically)

// => Configure Inter font (Latin)
const inter = Inter({
  subsets: ['latin'],                       // => Only load Latin characters
  display: 'swap',                          // => Font display strategy (swap for better performance)
  variable: '--font-inter',                 // => CSS variable name
});

// => Configure Amiri font (Arabic)
const amiri = Amiri({
  weight: ['400', '700'],                   // => Specific weights only
  subsets: ['arabic'],                      // => Only load Arabic characters
  display: 'swap',
  variable: '--font-amiri',
});

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" className={`${inter.variable} ${amiri.variable}`}>
      {/* => Apply font CSS variables to html element */}

      <body className={inter.className}>
        {/* => Default font is Inter */}
        {children}
      </body>
    </html>
  );
}

// app/components/ArabicText.tsx
export function ArabicText({ children }: { children: React.ReactNode }) {
  return (
    <p style={{ fontFamily: 'var(--font-amiri)' }}>
      {/* => Use Amiri font for Arabic text */}
      {children}
    </p>
  );
}

// Alternative: Local fonts
// app/layout.tsx
import localFont from 'next/font/local';

const customFont = localFont({
  src: './fonts/CustomFont.woff2',          // => Path to local font file
  display: 'swap',
  variable: '--font-custom',
});

// app/layout.tsx
import Script from 'next/script';
// => Import Script component

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}

        {/* => Critical analytics script (load after interactive) */}
        <Script
          src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
          strategy="afterInteractive"
          // => afterInteractive: load after page interactive (default)
          // => Doesn't block user interaction
        />

        {/* => Initialize analytics */}
        <Script id="google-analytics" strategy="afterInteractive">
          {`
            window.dataLayer = window.dataLayer || [];
            function gtag(){dataLayer.push(arguments);}
            gtag('js', new Date());
            gtag('config', 'GA_MEASUREMENT_ID');
          `}
        </Script>

        {/* => Non-critical widget (lazy load) */}
        <Script
          src="https://widget.example.com/widget.js"
          strategy="lazyOnload"
          // => lazyOnload: load after page fully loaded
          // => Lowest priority, doesn't affect performance
        />

        {/* => Script with callback */}
        <Script
          src="https://maps.googleapis.com/maps/api/js?key=API_KEY"
          strategy="afterInteractive"
          onLoad={() => {
            // => Callback when script loaded
            console.log('Google Maps script loaded');
          }}
          onError={(e) => {
            // => Callback on load error
            console.error('Failed to load Google Maps', e);
          }}
        />
      </body>
    </html>
  );
}

// app/components/CustomWidget.tsx
'use client';

import Script from 'next/script';

export function CustomWidget() {
  return (
    <>
      {/* => Component-level script (only loads when component renders) */}
      <Script
        src="https://widget.example.com/component-widget.js"
        strategy="lazyOnload"
      />

      <div id="widget-container" />
    </>
  );
}

// app/api/og/route.tsx
// => API route that generates OG images
import { ImageResponse } from 'next/og';
// => Import ImageResponse for OG image generation

export const runtime = 'edge';              // => Use Edge Runtime for fast responses

export async function GET(request: Request) {
  // => Extract query parameters
  const { searchParams } = new URL(request.url);
  const title = searchParams.get('title') || 'Default Title';
  // => title is "Zakat Guide" from /api/og?title=Zakat%20Guide

  // => Return ImageResponse (generates image)
  return new ImageResponse(
    (
      // => JSX-like syntax for image layout
      <div
        style={{
          display: 'flex',
          flexDirection: 'column',
          alignItems: 'center',
          justifyContent: 'center',
          width: '100%',
          height: '100%',
          background: 'linear-gradient(135deg, #0173B2 0%, #029E73 100%)',
          color: 'white',
          fontFamily: 'sans-serif',
        }}
      >
        <h1 style={{ fontSize: '64px', margin: 0 }}>{title}</h1>
        <p style={{ fontSize: '32px', margin: '20px 0 0' }}>Islamic Finance Platform</p>
      </div>
    ),
    {
      width: 1200,                          // => OG image width (recommended: 1200px)
      height: 630,                          // => OG image height (recommended: 630px)
    }
  );
  // => Returns PNG image with dynamic content
}

// app/blog/[slug]/page.tsx
import { Metadata } from 'next';

export async function generateMetadata({
  params,
}: {
  params: { slug: string };
}): Promise<Metadata> {
  // => Fetch post data
  const post = { title: 'Zakat Guide', description: 'Complete guide to Zakat calculation' };

  // => Generate OG image URL
  const ogImageUrl = new URL('/api/og', 'https://example.com');
  ogImageUrl.searchParams.set('title', post.title);
  // => ogImageUrl is "https://example.com/api/og?title=Zakat%20Guide"

  return {
    title: post.title,
    description: post.description,
    openGraph: {
      title: post.title,
      description: post.description,
      images: [
        {
          url: ogImageUrl.toString(),
          // => Dynamic OG image for this post
          width: 1200,
          height: 630,
        },
      ],
    },
    twitter: {
      card: 'summary_large_image',
      title: post.title,
      description: post.description,
      images: [ogImageUrl.toString()],
    },
  };
}

export default function BlogPostPage() {
  return (
    <article>
      <h1>Blog Post</h1>
    </article>
  );
}

// app/products/[id]/page.tsx
import { Metadata } from 'next';

// => Product data
const product = {
  id: '1',
  name: 'Murabaha Financing',
  description: 'Sharia-compliant cost-plus financing for asset purchases',
  price: 1000000,
  currency: 'IDR',
  availability: 'InStock',
  rating: 4.8,
  reviewCount: 127,
};

export const metadata: Metadata = {
  title: `${product.name} | Islamic Finance`,
  description: product.description,
};

export default function ProductPage() {
  // => JSON-LD structured data
  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    description: product.description,
    offers: {
      '@type': 'Offer',
      price: product.price,
      priceCurrency: product.currency,
      availability: `https://schema.org/${product.availability}`,
    },
    aggregateRating: {
      '@type': 'AggregateRating',
      ratingValue: product.rating,
      reviewCount: product.reviewCount,
    },
  };

  return (
    <div>
      {/* => Inject JSON-LD in script tag */}
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
      {/* => Search engines parse this for rich results */}

      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <p>Price: {product.currency} {product.price.toLocaleString()}</p>
      <p>Rating: {product.rating} ({product.reviewCount} reviews)</p>
    </div>
  );
}

// Alternative: Article structured data
// app/blog/[slug]/page.tsx
export default function BlogPostPage() {
  const articleJsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline: 'Zakat Calculation Guide',
    description: 'Complete guide to calculating Zakat on wealth',
    author: {
      '@type': 'Person',
      name: 'Ahmad Ibrahim',
    },
    datePublished: '2026-01-15',
    dateModified: '2026-01-20',
    publisher: {
      '@type': 'Organization',
      name: 'Islamic Finance Platform',
      logo: {
        '@type': 'ImageObject',
        url: 'https://example.com/logo.png',
      },
    },
  };

  return (
    <article>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(articleJsonLd) }}
      />
      <h1>Zakat Calculation Guide</h1>
    </article>
  );
}

// env.ts
// => Environment variable validation schema
import { z } from "zod";

// => Define schema for environment variables
const envSchema = z.object({
  // => Required variables
  DATABASE_URL: z.string().url(),
  // => Must be valid URL

  NEXTAUTH_SECRET: z.string().min(32),
  // => Minimum 32 characters (security)

  NEXTAUTH_URL: z.string().url(),

  // => Optional variables with defaults
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),

  // => Public variables (NEXT_PUBLIC_ prefix)
  NEXT_PUBLIC_API_URL: z.string().url(),
});

// => Parse and validate environment variables at build time
const env = envSchema.parse({
  DATABASE_URL: process.env.DATABASE_URL,
  NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET,
  NEXTAUTH_URL: process.env.NEXTAUTH_URL,
  NODE_ENV: process.env.NODE_ENV,
  NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
});
// => If validation fails, build fails with clear error

// => Export typed environment variables
export default env;

// app/lib/db.ts
import env from "../env";

// => Use typed environment variables
export const dbConnection = env.DATABASE_URL;
// => env.DATABASE_URL is string (type-safe)

// app/config.ts
import env from "./env";

export const config = {
  database: {
    url: env.DATABASE_URL, // => Type: string (validated URL)
  },
  auth: {
    secret: env.NEXTAUTH_SECRET, // => Type: string (min 32 chars)
    url: env.NEXTAUTH_URL,
  },
  api: {
    url: env.NEXT_PUBLIC_API_URL, // => Public, accessible in browser
  },
  isProduction: env.NODE_ENV === "production",
};

// Usage in components/actions
// app/actions.ts
("use server");

import { config } from "./config";

export async function connectToDatabase() {
  // => Type-safe config access
  const dbUrl = config.database.url; // => Type: string
  // => No need for optional chaining or type assertions

  console.log(`Connecting to database: ${dbUrl}`);
}

// instrumentation.ts
// => Special file: Next.js loads this before app initialization
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    // => Only instrument Node.js runtime (not Edge)
    const { registerOTel } = await import("@vercel/otel");

    registerOTel({
      serviceName: "islamic-finance-platform",
      // => Service name in tracing system
    });
  }
}

// app/lib/monitoring.ts
import { trace } from "@opentelemetry/api";

// => Create tracer for custom spans
const tracer = trace.getTracer("app");

export async function tracedDatabaseQuery<T>(name: string, query: () => Promise<T>): Promise<T> {
  // => Create span for database query
  return tracer.startActiveSpan(`db.query.${name}`, async (span) => {
    try {
      const result = await query();
      // => Query succeeded

      span.setStatus({ code: 1 }); // => 1 = OK
      span.end();

      return result;
    } catch (error) {
      // => Query failed
      span.setStatus({
        code: 2, // => 2 = ERROR
        message: error instanceof Error ? error.message : "Unknown error",
      });
      span.recordException(error as Error);
      span.end();

      throw error;
    }
  });
}

// app/lib/data.ts
import { prisma } from "./prisma";
import { tracedDatabaseQuery } from "./monitoring";

export async function getPosts() {
  // => Traced database query
  return tracedDatabaseQuery("get-posts", async () => {
    return prisma.post.findMany();
  });
  // => Appears in tracing system with timing and status
}

// app/api/health/route.ts
// => Health check endpoint for monitoring
export async function GET() {
  try {
    // => Check database connection
    await prisma.$queryRaw`SELECT 1`;

    return Response.json({ status: "healthy" });
  } catch (error) {
    return Response.json({ status: "unhealthy" }, { status: 503 });
  }
}

// app/lib/rate-limit.ts
import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

// => Create Redis client
const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
});

// => Create rate limiter (sliding window)
const ratelimit = new Ratelimit({
  redis,
  limiter: Ratelimit.slidingWindow(10, "10 s"),
  // => 10 requests per 10 seconds
  analytics: true, // => Track usage analytics
});

export async function checkRateLimit(identifier: string) {
  // => Check rate limit for identifier (user ID, IP address, etc.)
  const { success, limit, reset, remaining } = await ratelimit.limit(identifier);
  // => success: boolean (request allowed?)
  // => limit: number (max requests)
  // => reset: number (timestamp when limit resets)
  // => remaining: number (requests remaining)

  return {
    allowed: success,
    limit,
    remaining,
    reset: new Date(reset),
  };
}

// app/api/donations/route.ts
import { NextRequest, NextResponse } from "next/server";
import { checkRateLimit } from "@/app/lib/rate-limit";

export async function POST(request: NextRequest) {
  // => Get client identifier (IP address)
  const ip = request.ip ?? request.headers.get("x-forwarded-for") ?? "anonymous";

  // => Check rate limit
  const rateLimit = await checkRateLimit(ip);

  if (!rateLimit.allowed) {
    // => Rate limit exceeded
    return NextResponse.json(
      {
        error: "Too many requests",
        limit: rateLimit.limit,
        reset: rateLimit.reset,
      },
      {
        status: 429, // => HTTP 429 Too Many Requests
        headers: {
          "X-RateLimit-Limit": rateLimit.limit.toString(),
          "X-RateLimit-Remaining": rateLimit.remaining.toString(),
          "X-RateLimit-Reset": rateLimit.reset.toISOString(),
        },
      },
    );
  }

  // => Rate limit passed, process request
  const body = await request.json();

  // => Handle donation
  console.log("Processing donation:", body);

  return NextResponse.json(
    { success: true },
    {
      headers: {
        // => Add rate limit headers to successful responses too
        "X-RateLimit-Limit": rateLimit.limit.toString(),
        "X-RateLimit-Remaining": rateLimit.remaining.toString(),
        "X-RateLimit-Reset": rateLimit.reset.toISOString(),
      },
    },
  );
}

// app/lib/secrets.ts
// => Import server-only at top of file
import 'server-only';
// => If this file imported in Client Component, build fails with error

// => Server-only function (accesses environment secrets)
export function getSecretKey() {
  // => This function should NEVER run on client
  return process.env.SECRET_API_KEY;
}

export async function queryDatabase(sql: string) {
  // => Database credentials only on server
  const db = process.env.DATABASE_URL;
  // => If accidentally imported in client code, build fails
  console.log(`Querying: ${sql}`);
}

// app/actions.ts
'use server';

// => Safe to import in Server Actions
import { getSecretKey, queryDatabase } from './lib/secrets';

export async function fetchUserData() {
  const apiKey = getSecretKey();            // => Server-side only
  await queryDatabase('SELECT * FROM users');

  return { success: true };
}

// app/components/ClientComponent.tsx
'use client';

// => This import would cause BUILD ERROR
// import { getSecretKey } from '../lib/secrets';
// => Error: "You're importing a component that needs server-only. Use it in a Server Component instead."

export default function ClientComponent() {
  return <div>Client Component</div>;
}

// Alternative: client-only protection
// app/lib/browser-only.ts
import 'client-only';
// => Ensures code only runs on client (never on server)

export function getLocalStorage(key: string) {
  // => window only exists on client
  return window.localStorage.getItem(key);
}

// app/dashboard/page.tsx
import { Suspense } from 'react';

// => Static component (pre-rendered at build time)
function DashboardShell() {
  return (
    <div>
      <header>
        <h1>Dashboard</h1>
        {/* => Static heading, pre-rendered */}
      </header>

      <nav>
        {/* => Static navigation, pre-rendered */}
        <a href="/dashboard">Overview</a>
        <a href="/dashboard/stats">Stats</a>
        <a href="/dashboard/settings">Settings</a>
      </nav>
    </div>
  );
}

// => Dynamic component (renders at request time)
async function UserGreeting() {
  // => Fetch user-specific data
  const user = { name: 'Ahmad', lastLogin: new Date() };

  return (
    <div>
      <p>Welcome back, {user.name}!</p>
      <p>Last login: {user.lastLogin.toLocaleString()}</p>
    </div>
  );
}

// => Another dynamic component
async function RecentActivity() {
  // => Fetch recent activity (user-specific)
  await new Promise(resolve => setTimeout(resolve, 1000));

  const activities = [
    { id: 1, text: 'Donated IDR 100,000' },
    { id: 2, text: 'Updated profile' },
  ];

  return (
    <ul>
      {activities.map(activity => (
        <li key={activity.id}>{activity.text}</li>
      ))}
    </ul>
  );
}

export default function DashboardPage() {
  return (
    <div>
      {/* => Static shell (pre-rendered) */}
      <DashboardShell />

      {/* => Dynamic sections (streamed) */}
      <Suspense fallback={<p>Loading greeting...</p>}>
        <UserGreeting />
      </Suspense>

      <Suspense fallback={<p>Loading activity...</p>}>
        <RecentActivity />
      </Suspense>
    </div>
  );
}
// => PPR behavior:
// => 1. Static shell served instantly from CDN (header, nav)
// => 2. Dynamic sections stream in as ready (greeting, activity)
// => Best of both: instant load + personalized content

// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

// => Middleware function type
type MiddlewareFunction = (request: NextRequest) => NextResponse | Promise<NextResponse> | void | Promise<void>;

// => Middleware composer
function chain(...middlewares: MiddlewareFunction[]) {
  return async (request: NextRequest) => {
    // => Run middlewares in sequence
    for (const middleware of middlewares) {
      const response = await middleware(request);
      // => If middleware returns response, stop chain
      if (response) return response;
    }

    // => No middleware returned response, continue
    return NextResponse.next();
  };
}

// => Logging middleware
function loggerMiddleware(request: NextRequest) {
  console.log(`[${new Date().toISOString()}] ${request.method} ${request.nextUrl.pathname}`);
  // => No return = continue to next middleware
}

// => Auth middleware
async function authMiddleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // => Check if route is protected
  if (pathname.startsWith("/dashboard")) {
    const authToken = request.cookies.get("auth_token");

    if (!authToken) {
      // => Not authenticated, redirect
      return NextResponse.redirect(new URL("/login", request.url));
      // => Returns response, stops chain
    }
  }
  // => Authenticated or public route, continue
}

// => Rate limit middleware
async function rateLimitMiddleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // => Only rate limit API routes
  if (pathname.startsWith("/api/")) {
    const ip = request.ip ?? "anonymous";

    // => Check rate limit (simplified)
    const isAllowed = true; // => Actual rate limit check here

    if (!isAllowed) {
      return NextResponse.json({ error: "Too many requests" }, { status: 429 });
    }
  }
}

// => Security headers middleware
function securityHeadersMiddleware(request: NextRequest) {
  const response = NextResponse.next();

  // => Add security headers
  response.headers.set("X-Frame-Options", "DENY");
  response.headers.set("X-Content-Type-Options", "nosniff");
  response.headers.set("Referrer-Policy", "strict-origin-when-cross-origin");

  return response;
}

// => Export chained middleware
export default chain(loggerMiddleware, authMiddleware, rateLimitMiddleware, securityHeadersMiddleware);
// => Middlewares run in order: log → auth → rate limit → security headers

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};