Overview

Static Site Generation (SSG) pre-renders pages at build time, creating static HTML files that can be served directly without server-side processing. When combined with internationalization, SSG generates pre-rendered versions for each locale.

Setup

Setup Requirements

To enable SSG with GT, you need:

1. Enable experimental SSG flag - configure experimentalEnableSSG: true
2. App Router with middleware routing - see middleware guide
3. Custom getStaticLocale function - for locale detection during static rendering

Step 1: Enable SSG in Configuration

// next.config.js
export default withGTConfig(nextConfig, {
  experimentalEnableSSG: true,
})

Step 2: Configure Middleware

Set up middleware for dynamic requests:

// proxy.ts (Next.js 16+) or middleware.ts (Next.js 15 and below)
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

export const config = {
  matcher: [
    "/((?!api|static|.*\\..*|_next).*)",
  ],
}

Step 3: Define Static Locale Detection

Create a getStaticLocale function for locale detection during static rendering:

Next.js 15.5+

// getStaticLocale.ts
import { locale } from "next/root-params";

export default async function getLocale() {
  return await locale();
}

Next.js 15.1-15.4

// getStaticLocale.ts  
import { unstable_rootParams } from "next/server";

export default async function getLocale() {
  return (await unstable_rootParams())?.locale;
}

Step 4: Configure generateStaticParams

Make sure you have generateStaticParams configured for your locales.

Additional Configuration

Static Region Detection (Optional)

You can also create a getStaticRegion function for customized region detection during static rendering:

// getStaticRegion.ts
import { locale } from "next/root-params";

export default async function getStaticRegion() {
  const currentLocale = await locale();
  // Your region detection logic based on locale
  return currentLocale?.startsWith('en') ? 'US' : 'EU';
}

Common Issues

Next.js version compatibility

For versions earlier than Next.js 15.1, there is no way to access URL path parameters during static generation. You will need to upgrade to Next.js 15.1 or later to use SSG with gt-next.

Pages Not Generating Statically

If your pages aren't being statically generated, ensure that:

• The experimentalEnableSSG flag is enabled
• Your getStaticLocale function is properly configured
• You have generateStaticParams set up

Layout outside of the [locale] directory

If you have a layout.tsx file outside of the [locale] directory, it will prevent static generation. You will likely see the following error:

The export locale was not found in module [next]/root-params.js [app-rsc] (ecmascript).
All exports of the module are statically known (It doesn't have dynamic exports). So it's known statically that the requested export doesn't exist.

All layout.tsx files must be inside the [locale] directory. For more information, see this related Next.js issue.

Further Reading

• Check out the middleware guide required for locale routing
• Read the release notes for this feature