getStaticProps

Если вы экспортируете функцию getStaticProps (Статическая генерация сайта) из страницы, Next.js будет предварительно рендерить эту страницу во время сборки, используя пропсы, возвращаемые getStaticProps.

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
}

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
}

Обратите внимание, что независимо от типа рендеринга любые props будут переданы в компонент страницы и могут быть просмотрены на стороне клиента в исходном HTML. Это необходимо для правильной гидратации страницы. Убедитесь, что вы не передаете в props никакой конфиденциальной информации, которая не должна быть доступна на клиенте.

Когда следует использовать getStaticProps?

Используйте getStaticProps, если:

• Данные, необходимые для рендеринга страницы, доступны во время сборки до запроса пользователя
• Данные поступают из headless CMS
• Страница должна быть предварительно отрендерена (для SEO) и быть очень быстрой — getStaticProps генерирует файлы HTML и JSON, которые могут кэшироваться CDN для повышения производительности
• Данные могут быть публично закэшированы (не специфичны для пользователя). Это условие может быть обойдено в определенных ситуациях с использованием Middleware для перезаписи пути.

Когда выполняется getStaticProps

getStaticProps всегда выполняется на сервере и никогда на клиенте. Вы можете проверить, что код внутри getStaticProps удален из клиентского бандла, с помощью этого инструмента.

• getStaticProps всегда выполняется во время next build
• getStaticProps выполняется в фоновом режиме при использовании fallback: true
• getStaticProps вызывается перед первоначальным рендерингом при использовании fallback: blocking
• getStaticProps выполняется в фоновом режиме при использовании revalidate
• getStaticProps выполняется по требованию в фоновом режиме при использовании revalidate()

При использовании Инкрементальной статической регенерации getStaticProps будет выполняться в фоновом режиме, пока устаревшая страница перевалидируется, а свежая страница отправляется в браузер.

getStaticProps не имеет доступа к входящему запросу (например, параметрам запроса или HTTP-заголовкам), так как генерирует статический HTML. Если вам нужен доступ к запросу для вашей страницы, рассмотрите использование Middleware вместе с getStaticProps.

Использование getStaticProps для получения данных из CMS

Следующий пример показывает, как можно получить список постов блога из CMS.

// 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` как проп во время сборки
  return {
    props: {
      posts,
    },
  }
}

// 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` как проп во время сборки
  return {
    props: {
      posts,
    },
  }
}

В справочнике API getStaticProps описаны все параметры и пропсы, которые можно использовать с getStaticProps.

Написание серверного кода напрямую

Поскольку getStaticProps выполняется только на сервере, он никогда не выполняется на клиенте. Он даже не включается в JS-бандл для браузера, поэтому можно писать прямые запросы к базе данных, не отправляя их в браузеры.

Это означает, что вместо получения данных через API route из getStaticProps (который сам получает данные из внешнего источника), можно написать серверный код напрямую в getStaticProps.

Рассмотрим следующий пример. API route используется для получения данных из CMS. Затем этот API route вызывается напрямую из getStaticProps. Это создает дополнительный вызов, снижая производительность. Вместо этого логику получения данных из CMS можно вынести в директорию lib/. Затем её можно использовать совместно с getStaticProps.

// Следующая функция используется совместно
// с getStaticProps и API routes
// из директории `lib/`
export async function loadPosts() {
  // Вызов внешнего API для получения постов
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}

// pages/blog.js
import { loadPosts } from '../lib/load-posts'

// Эта функция выполняется только на стороне сервера
export async function getStaticProps() {
  // Вместо вызова вашего `/api` route можно вызвать ту же
  // функцию напрямую в `getStaticProps`
  const posts = await loadPosts()

  // Возвращаемые props будут переданы в компонент страницы
  return { props: { posts } }
}

Альтернативно, если вы не используете API routes для получения данных, то API fetch() может быть использован напрямую в getStaticProps для получения данных.

Чтобы проверить, что Next.js удаляет из клиентского бандла, можно использовать инструмент next-code-elimination.

Статическая генерация HTML и JSON

Когда страница с getStaticProps предварительно рендерится во время сборки, помимо HTML-файла страницы, Next.js генерирует JSON-файл с результатом выполнения getStaticProps.

Этот JSON-файл используется при клиентской маршрутизации через next/link или next/router. При переходе на страницу, предварительно отрендеренную с помощью getStaticProps, Next.js получает этот JSON-файл (предварительно вычисленный во время сборки) и использует его как пропсы для компонента страницы. Это означает, что клиентские переходы между страницами не вызывают getStaticProps, так как используется только экспортированный JSON.

При использовании Инкрементальной статической регенерации getStaticProps будет выполняться в фоновом режиме для генерации JSON, необходимого для клиентской навигации. Вы можете увидеть это в виде нескольких запросов для одной и той же страницы, однако это ожидаемо и не влияет на производительность для конечного пользователя.

Где можно использовать getStaticProps

getStaticProps может быть экспортирован только из страницы. Его нельзя экспортировать из нестраничных файлов, _app, _document или _error.

Одно из ограничений связано с тем, что React должен иметь все необходимые данные до рендеринга страницы.

Также необходимо экспортировать getStaticProps как отдельную функцию — он не будет работать, если добавить getStaticProps как свойство компонента страницы.

Полезно знать: если вы создали пользовательское приложение, убедитесь, что передаете pageProps в компонент страницы, как показано в документации, иначе пропсы будут пустыми.

Выполнение при каждом запросе в режиме разработки

В режиме разработки (next dev) getStaticProps будет вызываться при каждом запросе.

Режим предпросмотра

Вы можете временно обойти статическую генерацию и рендерить страницу во время запроса вместо времени сборки, используя Режим предпросмотра. Например, если вы используете headless CMS и хотите просмотреть черновики перед их публикацией.