getStaticPaths

ページが動的ルートを持ち、getStaticPropsを使用している場合、静的に生成するパスのリストを定義する必要があります。

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

pages/repo/[name].tsx

TypeScript

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
}

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

getStaticPathsをいつ使用するべきか

以下の条件に該当する動的ルートを使用するページを静的に事前レンダリングする場合、getStaticPathsを使用する必要があります：

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

getStaticPathsはいつ実行されるか

getStaticPathsは本番環境でのビルド時にのみ実行され、実行時には呼び出されません。getStaticPaths内に記述されたコードがクライアント側のバンドルから削除されることをこのツールで検証できます。

getStaticPropsはgetStaticPathsとどのように連携するか

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

getStaticPathsをどこで使用できるか

getStaticPathsはgetStaticPropsと必ず一緒に使用する必要があります
getStaticPathsはgetServerSidePropsと一緒に使用できません
getStaticPropsを使用する動的ルートからgetStaticPathsをエクスポートできます
getStaticPathsは非ページファイル（例：componentsフォルダ）からエクスポートできません
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 }
}