Menu

getStaticProps

ページからgetStaticProps（静的サイト生成）という関数をエクスポートすると、Next.jsはgetStaticPropsが返すpropsを使用して、ビルド時にこのページを事前レンダリングします。

pages/index.tsx
TypeScript
import type { InferGetStaticPropsType, GetStaticProps } from 'next'
 
type Repo = {
  name: string
  stargazers_count: number
}
 
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
}

レンダリングタイプに関わらず、すべてのpropsがページコンポーネントに渡され、初期HTMLでクライアント側で表示できることに注意してください。これは、ページを正しくハイドレートできるようにするためです。propsで機密情報をクライアントに利用可能にしないように注意してください。

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

いつ getStaticProps を使用すべきか

以下の場合にgetStaticPropsを使用すべきです：

  • ページをレンダリングするために必要なデータがユーザーのリクエスト前のビルド時に利用可能
  • データがヘッドレスCMSから取得される
  • ページをSEOのために事前レンダリングし、非常に高速にする必要がある — getStaticPropsはHTMLとJSONファイルを生成し、どちらもパフォーマンスのためにCDNでキャッシュできる
  • データを公開でキャッシュ可能（ユーザー特有のデータではない）。この条件は、ミドルウェアを使用してパスを書き換えることで、特定の状況で回避できます。

getStaticPropsはいつ実行されるか

getStaticPropsは常にサーバー上で実行され、クライアント上では決して実行されません。getStaticProps内に記述されたコードがクライアント側のバンドルから削除されることは、このツールで検証できます。

  • getStaticPropsは常にnext build中に実行されます
  • getStaticPropsはfallback: trueを使用する際にバックグラウンドで実行されます
  • getStaticPropsはfallback: blockingを使用する際に初期レンダリング前に呼び出されます
  • getStaticPropsはrevalidateを使用する際にバックグラウンドで実行されます
  • getStaticPropsはrevalidate()を使用する際にバックグラウンドでオンデマンドで実行されます

Incremental Static Regenerationと組み合わせると、getStaticPropsは古いページが再検証されている間にバックグラウンドで実行され、ブラウザに新しいページが提供されます。

getStaticPropsは静的HTMLを生成するため、受信リクエスト（クエリパラメータやHTTPヘッダーなど）にアクセスできません。ページのリクエストにアクセスする必要がある場合は、getStaticPropsに加えてミドルウェアの使用を検討してください。

getStaticPropsを使用してCMSからデータを取得する

次の例は、CMSからブログ記事のリストを取得する方法を示しています。

pages/blog.tsx
TypeScript
// postsはgetStaticProps()によってビルド時に設定されます
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}
 
// この関数はサーバー側のビルド時に呼び出されます。
// クライアント側では呼び出されないため、直接
// データベースクエリを実行できます。
export async function getStaticProps() {
  // 外部APIエンドポイントを呼び出して投稿を取得します。
  // 任意のデータ取得ライブラリを使用できます
  const res = await fetch('https://.../posts')
  const posts = await res.json()
 
  // { props: { posts } }を返すことで、Blogコンポーネントは
  // ビルド時に`posts`をpropsとして受け取ります
  return {
    props: {
      posts,
    },
  }
}

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

サーバー側のコードを直接記述する

getStaticPropsはサーバー側でのみ実行されるため、クライアント側では決して実行されません。ブラウザ用のJSバンドルに含まれることもないため、データベースクエリをブラウザに送信することなく、直接記述できます。

つまり、getStaticPropsからAPIルートを取得する（それ自体が外部ソースからデータを取得する）代わりに、getStaticProps内にサーバー側のコードを直接記述できます。

次の例を参照してください。APIルートは、CMSからデータを取得するために使用されます。そのAPIルートはgetStaticPropsから直接呼び出されます。これにより追加の呼び出しが発生し、パフォーマンスが低下します。代わりに、CMSからデータを取得するためのロジックは、lib/ディレクトリを使用して共有できます。その後、getStaticPropsと共有できます。

lib/load-posts.js
// 次の関数は
// getStaticPropsとAPIルートで
// `lib/`ディレクトリから共有されます
export async function loadPosts() {
  // 外部APIエンドポイントを呼び出して投稿を取得
  const res = await fetch('https://.../posts/')
  const data = await res.json()
 
  return data
}
pages/blog.js
// pages/blog.js
import { loadPosts } from '../lib/load-posts'
 
// この関数はサーバー側でのみ実行されます
export async function getStaticProps() {
  // `/api`ルートを取得する代わりに、同じ
  // 関数を`getStaticProps`内で直接呼び出せます
  const posts = await loadPosts()
 
  // 返されたPropsはページコンポーネントに渡されます
  return { props: { posts } }
}

あるいは、データ取得にAPIルートを使用していない場合、getStaticPropsでデータを取得するために直接fetch() APIを使用できます。

Next.jsがクライアント側のバンドルから何を削除するかを確認するには、next-code-elimination toolを使用できます。

HTMLとJSONの両方を静的に生成

getStaticPropsを持つページがビルド時に事前レンダリングされると、ページHTMLファイルに加えて、Next.jsはgetStaticPropsの実行結果を含むJSONファイルを生成します。

このJSONファイルは、next/linkまたはnext/routerを通じたクライアントサイドルーティングで使用されます。getStaticPropsを使用してプリレンダリングされたページに移動すると、Next.jsはこのJSONファイル（ビルド時に事前計算）をフェッチし、ページコンポーネントのプロップとして使用します。つまり、クライアントサイドのページ遷移では、エクスポートされたJSONのみが使用されるため、getStaticPropsは呼び出されません。

インクリメンタル静的生成を使用する場合、getStaticPropsはクライアントサイドナビゲーションに必要なJSONを生成するためにバックグラウンドで実行されます。同じページに対して複数のリクエストが行われることがありますが、これは意図的なものであり、エンドユーザーのパフォーマンスには影響しません。

getStaticPropsをどこで使用できるか

getStaticPropsはページからのみエクスポートできます。ページ以外のファイル、_app、_document、_errorからはエクスポートできません。

この制限の理由の1つは、Reactがページをレンダリングする前にすべての必要なデータを持っている必要があるためです。

また、getStaticPropsはスタンドアロン関数としてエクスポートする必要があります。ページコンポーネントのプロパティとしてgetStaticPropsを追加しても機能しません。

補足: カスタムアプリを作成した場合は、リンクされたドキュメントに示されているようにpagePropsをページコンポーネントに渡していることを確認してください。そうしないと、プロップは空になります。

開発環境では毎回リクエスト時に実行

開発環境（next dev）では、getStaticPropsは毎回のリクエストで呼び出されます。

プレビューモード

プレビューモードを使用すると、静的生成を一時的にバイパスし、ビルド時ではなくリクエスト時にページをレンダリングできます。例えば、ヘッドレスCMSを使用していて、公開前に下書きをプレビューしたい場合などです。