getStaticPaths

ページがダイナミックルートを使用しており、getStaticProps を利用する場合、静的に生成するパスのリストを定義する必要があります。

ダイナミックルートを使用するページから getStaticPaths 関数（静的サイト生成）をエクスポートすると、Next.js は getStaticPaths で指定されたすべてのパスを静的に事前レンダリングします。

import type {
  InferGetStaticPropsType,
  GetStaticProps,
  GetStaticPaths,
} from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getStaticPaths = (async () => {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // 以下の「paths」セクションを参照
    ],
    fallback: true, // false または "blocking"
  }
}) satisfies GetStaticPaths

export const getStaticProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetStaticProps<{
  repo: Repo
}>

export default function Page({
  repo,
}: InferGetStaticPropsType<typeof getStaticProps>) {
  return repo.stargazers_count
}

export async function getStaticPaths() {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // 以下の「paths」セクションを参照
    ],
    fallback: true, // false または "blocking"
  }
}

export async function getStaticProps() {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}

export default function Page({ repo }) {
  return repo.stargazers_count
}

getStaticPaths API リファレンスでは、getStaticPaths で使用できるすべてのパラメーターとプロパティについて説明しています。

getStaticPaths を使用すべきタイミング

以下の場合に getStaticPaths を使用するべきです:

ダイナミックルートを使用するページを静的に事前レンダリングする場合
データがヘッドレス CMS から取得される場合
データがデータベースから取得される場合
データがファイルシステムから取得される場合
データが公開キャッシュ可能な場合（ユーザー固有でない）
ページが SEO のために事前レンダリングされ、非常に高速である必要がある場合 — getStaticProps は HTML と JSON ファイルを生成し、どちらも CDN でキャッシュ可能でパフォーマンス向上に役立ちます

getStaticPaths の実行タイミング

getStaticPaths は本番環境のビルド時のみ実行され、ランタイム中には呼び出されません。このツールを使用して、getStaticPaths 内のコードがクライアントサイドバンドルから削除されていることを確認できます。

getStaticPaths に関連する getStaticProps の実行方法

getStaticProps はビルド時に返された paths に対して next build 中に実行されます
fallback: true を使用時にはバックグラウンドで getStaticProps が実行されます
fallback: blocking を使用時には初期レンダリング前に getStaticProps が呼び出されます

getStaticPaths の使用場所

getStaticPaths は必ず getStaticProps と一緒に使用する必要があります
getServerSideProps と一緒に getStaticPaths を 使用できません
getStaticProps も使用するダイナミックルートから getStaticPaths をエクスポートできます
非ページファイル（例: components フォルダ）から getStaticPaths を エクスポートできません
getStaticPaths はページコンポーネントのプロパティとしてではなく、スタンドアロン関数としてエクスポートする必要があります

開発環境でのリクエストごとの実行

開発環境 (next dev) では、getStaticPaths がリクエストごとに呼び出されます。

オンデマンドでのパス生成

getStaticPaths では、fallback を使用してオンデマンドで生成する代わりに、ビルド時にどのページを生成するかを制御できます。ビルド時に多くのページを生成すると、ビルドが遅くなります。

paths に空の配列を返すことで、すべてのページの生成をオンデマンドに延期できます。これは特に Next.js アプリケーションを複数の環境にデプロイする場合に役立ちます。例えば、プレビュー環境ではすべてのページをオンデマンドで生成することで（本番ビルドでは行わず）、ビルドを高速化できます。これは数百/数千の静的ページがあるサイトに有効です。

pages/posts/[id].js

export async function getStaticPaths() {
  // プレビュー環境で true の場合
  // 静的ページを事前レンダリングしない
  // （ビルドは高速化されるが、初期ページ読み込みは遅くなる）
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }

  // 外部APIエンドポイントを呼び出して投稿を取得
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // 投稿に基づいて事前レンダリングするパスを取得
  // 本番環境ではすべてのページを事前レンダリング
  // （ビルドは遅くなるが、初期ページ読み込みは高速化）
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // { fallback: false } は他のルートを404にする
  return { paths, fallback: false }
}