getStaticProps

Si vous exportez une fonction appelée getStaticProps (Génération de site statique) depuis une page, Next.js pré-rendra cette page au moment du build en utilisant les props retournées par 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
}

Notez que quel que soit le type de rendu, toutes les props seront transmises au composant de page et peuvent être consultées côté client dans le HTML initial. Ceci permet à la page d'être hydratée correctement. Assurez-vous de ne pas transmettre d'informations sensibles qui ne devraient pas être disponibles côté client dans les props.

La référence API de getStaticProps couvre tous les paramètres et props pouvant être utilisés avec getStaticProps.

Quand utiliser getStaticProps ?

Vous devriez utiliser getStaticProps si :

Les données nécessaires au rendu de la page sont disponibles au moment du build avant la requête d'un utilisateur
Les données proviennent d'un CMS headless
La page doit être pré-rendue (pour le SEO) et être très rapide — getStaticProps génère des fichiers HTML et JSON, qui peuvent tous deux être mis en cache par un CDN pour des performances optimales
Les données peuvent être mises en cache publiquement (non spécifiques à un utilisateur). Cette condition peut être contournée dans certaines situations spécifiques en utilisant un Middleware pour réécrire le chemin.

Quand getStaticProps s'exécute-t-il

getStaticProps s'exécute toujours côté serveur et jamais côté client. Vous pouvez vérifier que le code écrit dans getStaticProps est supprimé du bundle côté client avec cet outil.

getStaticProps s'exécute toujours pendant next build
getStaticProps s'exécute en arrière-plan lors de l'utilisation de fallback: true
getStaticProps est appelé avant le rendu initial lors de l'utilisation de fallback: blocking
getStaticProps s'exécute en arrière-plan lors de l'utilisation de revalidate
getStaticProps s'exécute à la demande en arrière-plan lors de l'utilisation de revalidate()

Lorsqu'il est combiné avec la Régénération Statique Incrémentielle, getStaticProps s'exécutera en arrière-plan pendant que la page obsolète est revalidée, et la page fraîche servie au navigateur.

getStaticProps n'a pas accès à la requête entrante (comme les paramètres de requête ou les en-têtes HTTP) car il génère du HTML statique. Si vous avez besoin d'accéder à la requête pour votre page, envisagez d'utiliser un Middleware en plus de getStaticProps.

Utiliser getStaticProps pour récupérer des données depuis un CMS

L'exemple suivant montre comment récupérer une liste d'articles de blog depuis un CMS.

// posts sera rempli au moment du build par getStaticProps()
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

// Cette fonction est appelée au moment du build côté serveur.
// Elle ne sera pas appelée côté client, vous pouvez donc même faire
// des requêtes directes à la base de données.
export async function getStaticProps() {
  // Appel à un endpoint API externe pour récupérer les posts.
  // Vous pouvez utiliser n'importe quelle bibliothèque de récupération de données
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // En retournant { props: { posts } }, le composant Blog
  // recevra `posts` comme prop au moment du build
  return {
    props: {
      posts,
    },
  }
}

La référence API de getStaticProps couvre tous les paramètres et props pouvant être utilisés avec getStaticProps.

Écrire du code serveur directement

Comme getStaticProps ne s'exécute que côté serveur, il ne s'exécutera jamais côté client. Il ne sera même pas inclus dans le bundle JS pour le navigateur, vous pouvez donc écrire des requêtes directes à la base de données sans qu'elles ne soient envoyées aux navigateurs.

Cela signifie qu'au lieu de récupérer une route API depuis getStaticProps (qui elle-même récupère des données depuis une source externe), vous pouvez écrire le code serveur directement dans getStaticProps.

Prenons l'exemple suivant. Une route API est utilisée pour récupérer des données depuis un CMS. Cette route API est ensuite appelée directement depuis getStaticProps. Cela produit un appel supplémentaire, réduisant les performances. À la place, la logique pour récupérer les données depuis le CMS peut être partagée en utilisant un répertoire lib/. Elle peut ensuite être partagée avec getStaticProps.

lib/load-posts.js

// La fonction suivante est partagée
// avec getStaticProps et les routes API
// depuis un répertoire `lib/`
export async function loadPosts() {
  // Appel à un endpoint API externe pour récupérer les posts
  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'

// Cette fonction ne s'exécute que côté serveur
export async function getStaticProps() {
  // Au lieu de récupérer votre route `/api`, vous pouvez appeler la même
  // fonction directement dans `getStaticProps`
  const posts = await loadPosts()

  // Les props retournées seront transmises au composant de page
  return { props: { posts } }
}

Alternativement, si vous n'utilisez pas les routes API pour récupérer des données, alors l'API fetch() peut être utilisée directement dans getStaticProps pour récupérer des données.

Pour vérifier ce que Next.js élimine du bundle côté client, vous pouvez utiliser l'outil next-code-elimination.

Génération statique de HTML et JSON

Lorsqu'une page avec getStaticProps est pré-rendue au moment du build, en plus du fichier HTML de la page, Next.js génère un fichier JSON contenant le résultat de l'exécution de getStaticProps.

Ce fichier JSON sera utilisé dans le routage côté client via next/link ou next/router. Lorsque vous naviguez vers une page pré-rendue utilisant getStaticProps, Next.js récupère ce fichier JSON (pré-calculé au moment du build) et l'utilise comme props pour le composant de page. Cela signifie que les transitions de page côté client n'appelleront pas getStaticProps car seul le JSON exporté est utilisé.

Lors de l'utilisation de la Régénération Statique Incrémentielle, getStaticProps s'exécutera en arrière-plan pour générer le JSON nécessaire à la navigation côté client. Vous pourrez voir cela sous la forme de multiples requêtes faites pour la même page, cependant, c'est intentionnel et n'a pas d'impact sur les performances pour l'utilisateur final.

Où puis-je utiliser getStaticProps

getStaticProps ne peut être exporté que depuis une page. Vous ne pouvez pas l'exporter depuis des fichiers non-pages, _app, _document, ou _error.

Une des raisons de cette restriction est que React a besoin d'avoir toutes les données requises avant que la page ne soit rendue.

De plus, vous devez exporter getStaticProps comme une fonction autonome — cela ne fonctionnera pas si vous ajoutez getStaticProps comme propriété du composant de page.

Bon à savoir : si vous avez créé une application personnalisée, assurez-vous de transmettre les pageProps au composant de page comme indiqué dans le document lié, sinon les props seront vides.

Exécution à chaque requête en développement

En développement (next dev), getStaticProps sera appelé à chaque requête.

Mode Prévisualisation

Vous pouvez temporairement contourner la génération statique et rendre la page au moment de la requête au lieu du moment du build en utilisant le Mode Prévisualisation. Par exemple, vous pourriez utiliser un CMS headless et vouloir prévisualiser des brouillons avant leur publication.

On this page