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
}

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

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

Когда следует использовать 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 will be populated at build time by getStaticProps()
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}
 
// This function gets called at build time on server-side.
// It won't be called on client-side, so you can even do
// direct database queries.
export async function getStaticProps() {
  // Call an external API endpoint to get posts.
  // You can use any data fetching library
  const res = await fetch('https://.../posts')
  const posts = await res.json()
 
  // By returning { props: { posts } }, the Blog component
  // will receive `posts` as a prop at build time
  return {
    props: {
      posts,
    },
  }
}

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

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

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

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

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

// The following function is shared
// with getStaticProps and API routes
// from a `lib/` directory
export async function loadPosts() {
  // Call an external API endpoint to get posts
  const res = await fetch('https://.../posts/')
  const data = await res.json()
 
  return data
}

// pages/blog.js
import { loadPosts } from '../lib/load-posts'
 
// This function runs only on the server side
export async function getStaticProps() {
  // Instead of fetching your `/api` route you can call the same
  // function directly in `getStaticProps`
  const posts = await loadPosts()
 
  // Props returned will be passed to the page component
  return { props: { posts } }
}

В качестве альтернативы, если вы не используете API маршруты для получения данных, то 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 должен иметь все необходимые данные до рендеринга страницы.

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

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

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

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

Режим предварительного просмотра

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