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 内のコードがクライアントサイドバンドルから削除されていることを確認できます。

getStaticProps が getStaticPaths に関連して実行される仕組み

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

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 }
}