コンテンツにスキップ
アプリケーションの構築データ取得getStaticPaths

getStaticPaths

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

動的ルートを使用するページから getStaticPaths (Static Site Generation) という関数をエクスポートすると、Next.js は getStaticPaths で指定されたすべてのパスを静的に事前レンダリングします。

pages/repo/[name].tsx
import type {
  InferGetStaticPropsType,
  GetStaticProps,
  GetStaticPaths,
} from 'next'
 
type Repo = {
  name: string
  stargazers_count: number
}
 
export const getStaticPaths = (async () => {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // See the "paths" section below
    ],
    fallback: true, // false or "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() {
  // When this is true (in preview environments) don't
  // prerender any static pages
  // (faster builds, but slower initial page load)
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }
 
  // Call an external API endpoint to get posts
  const res = await fetch('https://.../posts')
  const posts = await res.json()
 
  // Get the paths we want to prerender based on posts
  // In production environments, prerender all pages
  // (slower builds, but faster initial page load)
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))
 
  // { fallback: false } means other routes should 404
  return { paths, fallback: false }
}