静的サイト生成

概要

Static Site Generation (SSG) はビルド時にページを事前レンダリングし、サーバーサイド処理を介さずに直接配信できる静的な HTML files を生成します。国際化と組み合わせると、SSG は各 locale ごとに事前レンダリング済みのバージョンを生成します。

セットアップ

セットアップ要件

GT で SSG を有効にするには、以下が必要です:

ミドルウェアルーティングを使った App Router - middleware guide を参照
カスタム getLocale 関数 - 静的レンダリング時の locale 検出のため
getRegion の無効化 - 静的レンダリング時のリージョン検出はサポートされていません
generateStaticParams 関数 - 各 locale 向けの静的パラメーター生成用

ステップ 1：ミドルウェアを設定する

動的リクエスト用のミドルウェアをセットアップします（middleware ガイドを参照）:

// proxy.ts (Next.js 16以降) または middleware.ts (Next.js 15以下)
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

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

ステップ 2: locale とリージョンの検出を定義する

静的レンダリング時に locale とリージョンを検出するための getLocale 関数と getRegion 関数を作成します。

Next.js 15.5以降

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

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

Next.js 15.1-15.4

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

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

ステップ 3: `getRegion` を無効にする

静的レンダリング中にはリージョン検出がサポートされていないため、特定のリージョンを返すように getRegion 関数を上書きする必要があります。

// getRegion.ts
export default async function getRegion() {
  return undefined;
}

ステップ 4: `generateStaticParams` を設定する

対応ロケールごとに generateStaticParams を設定していることを確認してください。

page.tsx

import { getLocales } from 'gt-next/server';

export async function generateStaticParams() {
  return getLocales().map((locale) => ({ locale }));
}

export default async function Page() {
  ...
}

追加設定

ルートディレクトリに getLocale.ts と getRegion.ts を配置したくない場合は、next.config.js ファイルで任意のディレクトリを指定できます。

// next.config.js
export default withGTConfig(nextConfig, {
  getLocalePath: 'src/i18n/getLocale.ts',
  getRegionPath: 'src/i18n/getRegion.ts',
})

よくある問題

Next.js バージョン互換性

Next.js 15.1 より前のバージョンでは、静的生成中に URL パスパラメータにアクセスする手段がありません。gt-next で SSG を利用するには、Next.js 15.1 以降にアップグレードする必要があります。

ページが静的生成されない場合

ページが静的に生成されていない場合は、次の点を確認してください。

getLocale と getRegion 関数が正しく設定されていること

`[locale]` ディレクトリ外の Layout/Page

[locale] ディレクトリの外側に layout.tsx や page.tsx ファイルがあると、静的生成が行われません。次のような Error が表示されるはずです。

エクスポート locale がモジュール [next]/root-params.js [app-rsc] (ecmascript) 内に見つかりませんでした。
このモジュールのすべてのエクスポートは静的に認識されています（動的なエクスポートはありません）。そのため、要求されたエクスポートが存在しないことが静的に判明しています。

すべての layout.tsx ファイルは [locale] ディレクトリ内に配置する必要があります。詳細については、関連する Next.js の issue を参照してください。

さらなる参考資料

locale ルーティングに必要なミドルウェアガイドを参照してください
レガシーな SSG パターンからの移行についてはリリースノートを参照してください

ミドルウェアルーティングを使った App Router - middleware guide を参照
カスタム getLocale 関数 - 静的レンダリング時の locale 検出のため
getRegion の無効化 - 静的レンダリング時のリージョン検出はサポートされていません
generateStaticParams 関数 - 各 locale 向けの静的パラメーター生成用

ステップ 1：ミドルウェアを設定する

動的リクエスト用のミドルウェアをセットアップします（middleware ガイドを参照）:

// proxy.ts (Next.js 16以降) または middleware.ts (Next.js 15以下)
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

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

ステップ 2: locale とリージョンの検出を定義する

静的レンダリング時に locale とリージョンを検出するための getLocale 関数と getRegion 関数を作成します。

Next.js 15.5以降

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

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

Next.js 15.1-15.4

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

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

ステップ 3: `getRegion` を無効にする

静的レンダリング中にはリージョン検出がサポートされていないため、特定のリージョンを返すように getRegion 関数を上書きする必要があります。

// getRegion.ts
export default async function getRegion() {
  return undefined;
}

ステップ 4: `generateStaticParams` を設定する

対応ロケールごとに generateStaticParams を設定していることを確認してください。

page.tsx

import { getLocales } from 'gt-next/server';

export async function generateStaticParams() {
  return getLocales().map((locale) => ({ locale }));
}

export default async function Page() {
  ...
}

追加設定

ルートディレクトリに getLocale.ts と getRegion.ts を配置したくない場合は、next.config.js ファイルで任意のディレクトリを指定できます。

// next.config.js
export default withGTConfig(nextConfig, {
  getLocalePath: 'src/i18n/getLocale.ts',
  getRegionPath: 'src/i18n/getRegion.ts',
})

getLocale と getRegion 関数が正しく設定されていること

`[locale]` ディレクトリ外の Layout/Page

[locale] ディレクトリの外側に layout.tsx や page.tsx ファイルがあると、静的生成が行われません。次のような Error が表示されるはずです。

エクスポート locale がモジュール [next]/root-params.js [app-rsc] (ecmascript) 内に見つかりませんでした。
このモジュールのすべてのエクスポートは静的に認識されています（動的なエクスポートはありません）。そのため、要求されたエクスポートが存在しないことが静的に判明しています。

すべての layout.tsx ファイルは [locale] ディレクトリ内に配置する必要があります。詳細については、関連する Next.js の issue を参照してください。

さらなる参考資料

locale ルーティングに必要なミドルウェアガイドを参照してください
レガシーな SSG パターンからの移行についてはリリースノートを参照してください

ミドルウェアルーティングを使った App Router - middleware guide を参照
カスタム getLocale 関数 - 静的レンダリング時の locale 検出のため
getRegion の無効化 - 静的レンダリング時のリージョン検出はサポートされていません
generateStaticParams 関数 - 各 locale 向けの静的パラメーター生成用

ステップ 1：ミドルウェアを設定する

動的リクエスト用のミドルウェアをセットアップします（middleware ガイドを参照）:

// proxy.ts (Next.js 16以降) または middleware.ts (Next.js 15以下)
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

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

ステップ 2: locale とリージョンの検出を定義する

静的レンダリング時に locale とリージョンを検出するための getLocale 関数と getRegion 関数を作成します。

Next.js 15.5以降

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

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

Next.js 15.1-15.4

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

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

ステップ 3: `getRegion` を無効にする

静的レンダリング中にはリージョン検出がサポートされていないため、特定のリージョンを返すように getRegion 関数を上書きする必要があります。

// getRegion.ts
export default async function getRegion() {
  return undefined;
}

ステップ 4: `generateStaticParams` を設定する

対応ロケールごとに generateStaticParams を設定していることを確認してください。

page.tsx

import { getLocales } from 'gt-next/server';

export async function generateStaticParams() {
  return getLocales().map((locale) => ({ locale }));
}

export default async function Page() {
  ...
}

追加設定

ルートディレクトリに getLocale.ts と getRegion.ts を配置したくない場合は、next.config.js ファイルで任意のディレクトリを指定できます。

// next.config.js
export default withGTConfig(nextConfig, {
  getLocalePath: 'src/i18n/getLocale.ts',
  getRegionPath: 'src/i18n/getRegion.ts',
})

getLocale と getRegion 関数が正しく設定されていること

`[locale]` ディレクトリ外の Layout/Page

[locale] ディレクトリの外側に layout.tsx や page.tsx ファイルがあると、静的生成が行われません。次のような Error が表示されるはずです。

エクスポート locale がモジュール [next]/root-params.js [app-rsc] (ecmascript) 内に見つかりませんでした。
このモジュールのすべてのエクスポートは静的に認識されています（動的なエクスポートはありません）。そのため、要求されたエクスポートが存在しないことが静的に判明しています。

すべての layout.tsx ファイルは [locale] ディレクトリ内に配置する必要があります。詳細については、関連する Next.js の issue を参照してください。

さらなる参考資料

locale ルーティングに必要なミドルウェアガイドを参照してください
レガシーな SSG パターンからの移行についてはリリースノートを参照してください

静的サイト生成

このページについて

静的サイト生成

このページについて

静的サイト生成

このページについて

GitHubGitHubでスターを付ける

GitHubGitHubでスターを付ける

GitHubでスターを付ける

GitHubでスターを付ける