Next.js Basics Explained: Pages, Routing, and Data Fetching

// File location: pages/products/[productId].js
// This single file handles EVERY product URL: /products/1, /products/42, etc.

import { useRouter } from 'next/router';

export default function ProductPage() {
  // useRouter gives us access to the URL parameters
  const router = useRouter();

  // productId comes from the filename [productId].js
  // On the URL /products/42, this will be the string '42'
  const { productId } = router.query;

  // During the initial render on the client, query can be empty
  // so we guard against that with a loading state
  if (!productId) {
    return <p>Loading product...</p>;
  }

  return (
    <div>
      <h1>Product Details</h1>
      {/* Shows the dynamic segment from the URL */}
      <p>You are viewing product ID: {productId}</p>
      <p>
        This page was generated by the file:
        pages/products/[productId].js
      </p>
    </div>
  );
}

// --- FOLDER STRUCTURE REFERENCE ---
// pages/
//   index.js          → renders at /
//   about.js          → renders at /about
//   products/
//     index.js        → renders at /products
//     [productId].js  → renders at /products/:productId
//   blog/
//     [slug].js       → renders at /blog/:slug

// File: pages/blog/[slug].js
// This page uses SSG — it's pre-built at deploy time
// Perfect for blog posts that don't change every minute

export default function BlogPost({ post }) {
  // 'post' comes from getStaticProps below — it's already resolved
  // by the time this component renders. No loading state needed!
  return (
    <article>
      <h1>{post.title}</h1>
      <p>By {post.author} on {post.publishedDate}</p>
      <div>{post.content}</div>
    </article>
  );
}

// getStaticPaths tells Next.js WHICH URLs to pre-build
// This runs at build time — not on every request
export async function getStaticPaths() {
  // In real life, fetch this list from your CMS or database
  const publishedSlugs = ['intro-to-nextjs', 'react-hooks-explained', 'css-grid-guide'];

  const paths = publishedSlugs.map((slug) => ({
    params: { slug }, // must match the [slug] in your filename
  }));

  return {
    paths,
    // fallback: false means unknown slugs return a 404
    // fallback: 'blocking' means unknown slugs trigger SSR on first hit, then cache
    fallback: false,
  };
}

// getStaticProps receives the slug and fetches that post's data
// Runs ONCE per slug at build time — never again (until revalidate triggers)
export async function getStaticProps({ params }) {
  // Simulating a CMS or database fetch using the slug from the URL
  const response = await fetch(`https://api.example.com/posts/${params.slug}`);
  const post = await response.json();

  return {
    props: { post }, // injected as props into BlogPost component above
    // revalidate: 60 means re-generate this page in the background
    // if a request comes in after 60 seconds — this is called ISR
    revalidate: 60,
  };
}

// --- WHEN TO USE WHAT ---
// getStaticProps    → blog posts, product pages, marketing pages (fast, SEO-friendly)
// getServerSideProps → user dashboards, pages needing live data or session cookies
// useEffect fetch   → post-login UI, private account pages, non-SEO content

// File: components/ProductCard.js
// Demonstrates real-world usage of next/link and next/image

import Link from 'next/link';
import Image from 'next/image';

export default function ProductCard({ product }) {
  return (
    <div className="product-card">
      {/*
        next/image vs plain <img>:
        - Automatically serves WebP format if browser supports it
        - Resizes to the rendered size — not the original 4000px source
        - Lazy loads by default (doesn't load until near viewport)
        - Prevents CLS (Cumulative Layout Shift) via the width/height aspect ratio
      */}
      <Image
        src={product.imageUrl}
        alt={product.name}       // alt is required — good for accessibility AND SEO
        width={400}              // intrinsic width of the image
        height={300}             // intrinsic height — sets the aspect ratio
        // Add priority={true} ONLY for above-the-fold images like hero banners
        // priority={true} tells Next.js to preload it, skipping lazy loading
      />

      <h2>{product.name}</h2>
      <p>${product.price}</p>

      {/*
        next/link vs plain <a>:
        - Client-side navigation — no full page reload
        - Prefetches the linked page HTML+JS in the background when visible
        - Falls back to normal <a> behaviour if JavaScript hasn't loaded yet
      */}
      <Link href={`/products/${product.id}`}>
        {/* As of Next.js 13+, you don't need a nested <a> tag anymore */}
        View Product Details
      </Link>
    </div>
  );
}

// Usage in a parent page:
// <ProductCard
//   product={{
//     id: 42,
//     name: 'Trail Running Shoes',
//     price: 129.99,
//     imageUrl: '/images/trail-shoes.jpg'
//   }}
// />

// File: app/products/[productId]/page.js  (App Router convention)
// Notice: no getStaticProps, no useRouter for data — just async/await directly

// This is a SERVER COMPONENT by default.
// It runs only on the server. Zero JS is sent to the browser for this component.
// That means: faster page loads, direct database access, no API layer needed.

export default async function ProductPage({ params }) {
  // params comes from the folder name [productId] — same concept as Pages Router
  const { productId } = params;

  // fetch() in Server Components is enhanced by Next.js
  // next: { revalidate: 3600 } is equivalent to ISR — cache for 1 hour
  const response = await fetch(
    `https://api.example.com/products/${productId}`,
    { next: { revalidate: 3600 } } // ISR-style caching built right into fetch
  );

  const product = await response.json();

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <p>Price: ${product.price}</p>

      {/*
        AddToCartButton needs onClick — that's client-side behaviour.
        We mark it 'use client' in its own file and import it here.
        The Server Component passes data down; the Client Component handles interaction.
      */}
      <AddToCartButton productId={productId} />
    </div>
  );
}

// --- app/components/AddToCartButton.js ---
// 'use client' at the top opts this file into client-side rendering
// Only components that NEED interactivity should be client components

'use client';

import { useState } from 'react';

export function AddToCartButton({ productId }) {
  const [added, setAdded] = useState(false);

  function handleClick() {
    // In real life: call your cart API here
    console.log(`Adding product ${productId} to cart`);
    setAdded(true);
  }

  return (
    <button onClick={handleClick}>
      {added ? 'Added to Cart ✓' : 'Add to Cart'}
    </button>
  );
}

// --- App Router API Route ---
// File: app/api/users/route.js
// Each HTTP method is a named export

import { NextResponse } from 'next/server';

// GET /api/users — list all users
export async function GET(request) {
  const { searchParams } = new URL(request.url);
  const page = parseInt(searchParams.get('page') || '1');
  const limit = parseInt(searchParams.get('limit') || '20');

  // In production: call your database here
  const users = await db.users.findMany({
    skip: (page - 1) * limit,
    take: limit,
  });

  return NextResponse.json({
    data: users,
    pagination: { page, limit },
  });
}

// POST /api/users — create a new user
export async function POST(request) {
  const body = await request.json();

  // Validate input
  if (!body.email || !body.name) {
    return NextResponse.json(
      { error: 'Email and name are required' },
      { status: 400 }
    );
  }

  const user = await db.users.create({ data: body });

  return NextResponse.json({ data: user }, { status: 201 });
}

// --- Middleware ---
// File: middleware.js (project root)
// Runs on every request before pages/API routes

import { NextResponse } from 'next/server';

export function middleware(request) {
  // Example: redirect unauthenticated users
  const token = request.cookies.get('auth-token');

  // Protect dashboard routes
  if (request.nextUrl.pathname.startsWith('/dashboard') && !token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  // Add request ID for tracing
  const response = NextResponse.next();
  response.headers.set('x-request-id', crypto.randomUUID());

  return response;
}

// Matcher controls which routes trigger middleware
export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
};

// File: next.config.js
// Production configuration that actually matters

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Image optimisation domains — required for next/image with remote images
  images: {
    domains: ['images.example.com', 'cdn.example.com'],
    // Or use remotePatterns for more control (Next.js 13+)
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
      },
    ],
  },

  // Headers: set caching policies for static assets
  async headers() {
    return [
      {
        // Cache static assets (JS, CSS, images) for 1 year
        source: '/_next/static/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, max-age=31536000, immutable',
          },
        ],
      },
      {
        // Cache API responses for 60 seconds
        source: '/api/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, s-maxage=60, stale-while-revalidate=300',
          },
        ],
      },
    ];
  },

  // Redirects: handle legacy URLs and SEO
  async redirects() {
    return [
      {
        source: '/old-blog/:slug',
        destination: '/blog/:slug',
        permanent: true, // 301 redirect — SEO-friendly
      },
    ];
  },

  // Rewrites: proxy external APIs through Next.js
  async rewrites() {
    return [
      {
        source: '/api/external/:path*',
        destination: 'https://external-api.example.com/:path*',
      },
    ];
  },

  // Bundle analysis — run ANALYZE=true next build to visualise
  // Identifies large dependencies that should be code-split
  ...(process.env.ANALYZE === 'true' && {
    webpack: (config) => {
      const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');
      config.plugins.push(
        new BundleAnalyzerPlugin({
          analyzerMode: 'static',
          reportFilename: './bundle-analysis.html',
        })
      );
      return config;
    },
  }),
};

module.exports = nextConfig;

// --- Production Checklist ---
//
// 1. Run ANALYZE=true next build — check bundle-analysis.html for large deps
// 2. Set Cache-Control headers for static assets (1 year, immutable)
// 3. Set Cache-Control for API routes (s-maxage + stale-while-revalidate)
// 4. Use next/image for all images — never use plain <img>
// 5. Use next/link for all internal navigation — never use plain <a>
// 6. Pre-render top pages with getStaticProps — serve from CDN
// 7. Use ISR for pages that change infrequently — not full SSR
// 8. Add middleware for auth — do not check auth in every page component