Static Site Generation with Next.js

Static generation pre-renders pages at build time. Here's how to use it effectively.

Basic Static Generation#

// App Router: Server Components are static by default
// app/page.tsx
export default function HomePage() {
  return (
    <main>
      <h1>Welcome</h1>
      <p>This page is statically generated</p>
    </main>
  );
}

// With data fetching
// app/posts/page.tsx
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    cache: 'force-cache', // Static generation (default)
  });
  return res.json();
}

export default async function PostsPage() {
  const posts = await getPosts();

  return (
    <ul>
      {posts.map((post: Post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

Dynamic Routes with generateStaticParams#

// app/posts/[slug]/page.tsx
interface PageProps {
  params: { slug: string };
}

// Generate static paths at build time
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts').then(r => r.json());

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

// Fetch data for each page
async function getPost(slug: string) {
  const res = await fetch(`https://api.example.com/posts/${slug}`);
  if (!res.ok) return null;
  return res.json();
}

export default async function PostPage({ params }: PageProps) {
  const post = await getPost(params.slug);

  if (!post) {
    notFound();
  }

  return (
    <article>
      <h1>{post.title}</h1>
      <div>{post.content}</div>
    </article>
  );
}

// Generate metadata
export async function generateMetadata({ params }: PageProps) {
  const post = await getPost(params.slug);

  return {
    title: post?.title ?? 'Post Not Found',
    description: post?.excerpt,
  };
}

Multiple Dynamic Segments#

// app/blog/[category]/[slug]/page.tsx
interface PageProps {
  params: {
    category: string;
    slug: string;
  };
}

export async function generateStaticParams() {
  const posts = await getAllPosts();

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

export default async function PostPage({ params }: PageProps) {
  const post = await getPost(params.category, params.slug);

  return (
    <article>
      <span>{params.category}</span>
      <h1>{post.title}</h1>
    </article>
  );
}

Incremental Static Regeneration (ISR)#

// Revalidate every 60 seconds
// app/products/page.tsx
async function getProducts() {
  const res = await fetch('https://api.example.com/products', {
    next: { revalidate: 60 }, // ISR: regenerate every 60 seconds
  });
  return res.json();
}

export default async function ProductsPage() {
  const products = await getProducts();

  return (
    <div>
      <h1>Products</h1>
      <ul>
        {products.map((product: Product) => (
          <li key={product.id}>{product.name}</li>
        ))}
      </ul>
    </div>
  );
}

// Or set at segment level
export const revalidate = 60;

export default async function Page() {
  // All data fetches in this route use 60 second revalidation
}

On-Demand Revalidation#

// app/api/revalidate/route.ts
import { revalidatePath, revalidateTag } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const { path, tag, secret } = await request.json();

  // Validate secret
  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ error: 'Invalid secret' }, { status: 401 });
  }

  // Revalidate by path
  if (path) {
    revalidatePath(path);
    return NextResponse.json({ revalidated: true, path });
  }

  // Revalidate by tag
  if (tag) {
    revalidateTag(tag);
    return NextResponse.json({ revalidated: true, tag });
  }

  return NextResponse.json({ error: 'Path or tag required' }, { status: 400 });
}

// Tag-based caching
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { tags: ['posts'] },
  });
  return res.json();
}

// Revalidate all posts
revalidateTag('posts');

// Revalidate specific path
revalidatePath('/posts');
revalidatePath('/posts/[slug]', 'page');

Static Export#

// next.config.js
module.exports = {
  output: 'export',
  // Optional: Set base path
  basePath: '/my-app',
  // Optional: Trailing slashes
  trailingSlash: true,
};

// Build static site
// npm run build
// Output in /out directory

Hybrid Approaches#

// Static page with client-side data
// app/dashboard/page.tsx
import { Suspense } from 'react';
import { DynamicData } from './DynamicData';

// Static shell
export default function DashboardPage() {
  return (
    <div>
      <h1>Dashboard</h1>
      {/* Static content */}
      <StaticSidebar />

      {/* Dynamic content loaded client-side */}
      <Suspense fallback={<LoadingSkeleton />}>
        <DynamicData />
      </Suspense>
    </div>
  );
}

// components/DynamicData.tsx
'use client';

import useSWR from 'swr';

export function DynamicData() {
  const { data, error } = useSWR('/api/stats', fetcher);

  if (error) return <div>Error loading data</div>;
  if (!data) return <div>Loading...</div>;

  return <div>Live stats: {data.value}</div>;
}

MDX Content#

// next.config.mjs
import createMDX from '@next/mdx';

const withMDX = createMDX({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  },
});

export default withMDX({
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
});

// app/posts/[slug]/page.tsx
import { compileMDX } from 'next-mdx-remote/rsc';
import fs from 'fs';
import path from 'path';

const postsDirectory = path.join(process.cwd(), 'content/posts');

export async function generateStaticParams() {
  const files = fs.readdirSync(postsDirectory);

  return files.map((filename) => ({
    slug: filename.replace(/\.mdx$/, ''),
  }));
}

async function getPost(slug: string) {
  const filePath = path.join(postsDirectory, `${slug}.mdx`);
  const source = fs.readFileSync(filePath, 'utf8');

  const { content, frontmatter } = await compileMDX({
    source,
    options: { parseFrontmatter: true },
  });

  return { content, frontmatter };
}

export default async function PostPage({ params }: { params: { slug: string } }) {
  const { content, frontmatter } = await getPost(params.slug);

  return (
    <article>
      <h1>{frontmatter.title}</h1>
      {content}
    </article>
  );
}

Performance Optimization#

// Preload critical data
import { preload } from 'react-dom';

export default async function Layout({ children }) {
  preload('/fonts/inter.woff2', { as: 'font' });

  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

// Image optimization
import Image from 'next/image';

export default function Page() {
  return (
    <Image
      src="/hero.jpg"
      alt="Hero image"
      width={1200}
      height={600}
      priority // LCP image
      placeholder="blur"
      blurDataURL="data:image/jpeg;base64,..."
    />
  );
}

// Static import for small images
import heroImage from '../public/hero.jpg';

<Image src={heroImage} alt="Hero" placeholder="blur" />

Build Output#

# Build and analyze
npm run build

# Output shows static/dynamic pages
Route (app)                    Size     First Load JS
┌ ○ /                         5.2 kB   89 kB
├ ○ /about                    2.1 kB   86 kB
├ ● /posts/[slug]             3.4 kB   87 kB
│   ├ /posts/first-post
│   └ /posts/second-post
└ λ /api/revalidate           0 B      0 B

○ (Static)   prerendered as static content
● (SSG)      prerendered as static HTML (uses generateStaticParams)
λ (Dynamic)  server-rendered on demand

Best Practices#

Static Generation:
✓ Use for content that doesn't change often
✓ Pre-render as many pages as possible
✓ Use ISR for frequently updated content
✓ Implement on-demand revalidation

Performance:
✓ Optimize images with next/image
✓ Preload critical assets
✓ Use static export when possible
✓ Minimize client-side JavaScript

Content:
✓ Use MDX for rich content
✓ Generate metadata statically
✓ Create sitemaps at build time
✓ Handle 404 pages properly

Static generation provides the best performance by pre-rendering pages at build time. Use ISR for content that updates periodically, on-demand revalidation for immediate updates, and client-side fetching for user-specific data. This hybrid approach gives you the best of both worlds.