Menu

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をエクスポートできます
  • 非ページファイル（例：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 }
}