Génération de site statique (SSG)

Exemples

Si une page utilise la génération statique, le HTML de la page est généré au moment de la construction. Cela signifie qu'en production, le HTML de la page est généré lorsque vous exécutez next build. Ce HTML sera ensuite réutilisé à chaque requête. Il peut être mis en cache par un CDN.

Dans Next.js, vous pouvez générer statiquement des pages avec ou sans données. Examinons chaque cas.

Génération statique sans données

Par défaut, Next.js pré-rend les pages en utilisant la génération statique sans récupération de données. Voici un exemple :

function About() {
  return <div>About</div>
}

export default About

Notez que cette page n'a pas besoin de récupérer de données externes pour être pré-rendue. Dans de tels cas, Next.js génère un seul fichier HTML par page lors de la construction.

Génération statique avec données

Certaines pages nécessitent la récupération de données externes pour le pré-rendu. Il existe deux scénarios, et un ou les deux peuvent s'appliquer. Dans chaque cas, vous pouvez utiliser ces fonctions que Next.js fournit :

Le contenu de votre page dépend de données externes : Utilisez getStaticProps.
Les chemins de votre page dépendent de données externes : Utilisez getStaticPaths (généralement en plus de getStaticProps).

Scénario 1 : Le contenu de votre page dépend de données externes

Exemple : Votre page de blog pourrait avoir besoin de récupérer la liste des articles de blog à partir d'un CMS (système de gestion de contenu).

// TODO : Besoin de récupérer `posts` (en appelant un point d'API)
//        avant que cette page puisse être pré-rendue.
export default function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}

Pour récupérer ces données lors du pré-rendu, Next.js vous permet d'exporter une fonction async appelée getStaticProps depuis le même fichier. Cette fonction est appelée au moment de la construction et vous permet de passer les données récupérées aux props de la page lors du pré-rendu.

export default function Blog({ posts }) {
  // Afficher les articles...
}

// Cette fonction est appelée au moment de la construction
export async function getStaticProps() {
  // Appeler un point d'API externe pour obtenir les articles
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // En retournant { props: { posts } }, le composant Blog
  // recevra `posts` comme prop au moment de la construction
  return {
    props: {
      posts,
    },
  }
}

Pour en savoir plus sur le fonctionnement de getStaticProps, consultez la documentation sur la récupération de données.

Scénario 2 : Les chemins de votre page dépendent de données externes

Next.js vous permet de créer des pages avec des routes dynamiques. Par exemple, vous pouvez créer un fichier appelé pages/posts/[id].js pour afficher un seul article de blog basé sur id. Cela vous permettra d'afficher un article de blog avec id: 1 lorsque vous accédez à posts/1.

Pour en savoir plus sur le routage dynamique, consultez la documentation sur le routage dynamique.

Cependant, l'id que vous souhaitez pré-rendre au moment de la construction peut dépendre de données externes.

Exemple : supposons que vous n'ayez ajouté qu'un seul article de blog (avec id: 1) à la base de données. Dans ce cas, vous ne voudriez pré-rendre que posts/1 au moment de la construction.

Plus tard, vous pourriez ajouter un deuxième article avec id: 2. Vous voudriez alors également pré-rendre posts/2.

Ainsi, les chemins de votre page qui sont pré-rendus dépendent de données externes. Pour gérer cela, Next.js vous permet d'exporter une fonction async appelée getStaticPaths depuis une page dynamique (pages/posts/[id].js dans ce cas). Cette fonction est appelée au moment de la construction et vous permet de spécifier les chemins que vous souhaitez pré-rendre.

// Cette fonction est appelée au moment de la construction
export async function getStaticPaths() {
  // Appeler un point d'API externe pour obtenir les articles
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Obtenir les chemins que nous voulons pré-rendre basés sur les articles
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // Nous pré-rendrons uniquement ces chemins au moment de la construction.
  // { fallback: false } signifie que les autres routes devraient renvoyer une 404.
  return { paths, fallback: false }
}

De plus, dans pages/posts/[id].js, vous devez exporter getStaticProps afin de pouvoir récupérer les données sur l'article avec cet id et les utiliser pour pré-rendre la page :

export default function Post({ post }) {
  // Afficher l'article...
}

export async function getStaticPaths() {
  // ...
}

// Cette fonction est également appelée au moment de la construction
export async function getStaticProps({ params }) {
  // params contient l'`id` de l'article.
  // Si la route est comme /posts/1, alors params.id est 1
  const res = await fetch(`https://.../posts/${params.id}`)
  const post = await res.json()

  // Passer les données de l'article à la page via props
  return { props: { post } }
}

Pour en savoir plus sur le fonctionnement de getStaticPaths, consultez la documentation sur la récupération de données.

Quand devrais-je utiliser la génération statique ?

Nous recommandons d'utiliser la génération statique (avec ou sans données) autant que possible car votre page peut être construite une fois et servie par un CDN, ce qui la rend beaucoup plus rapide que si un serveur rendait la page à chaque requête.

Vous pouvez utiliser la génération statique pour de nombreux types de pages, notamment :

Pages marketing
Articles de blog et portfolios
Listes de produits e-commerce
Aide et documentation

Vous devriez vous demander : "Puis-je pré-rendre cette page avant la requête d'un utilisateur ?" Si la réponse est oui, alors vous devriez choisir la génération statique.

D'un autre côté, la génération statique n'est pas une bonne idée si vous ne pouvez pas pré-rendre une page avant la requête d'un utilisateur. Peut-être que votre page affiche des données fréquemment mises à jour, et le contenu de la page change à chaque requête.

Dans de tels cas, vous pouvez faire l'une des choses suivantes :

Utiliser la génération statique avec récupération de données côté client : Vous pouvez ignorer le pré-rendu de certaines parties d'une page et utiliser ensuite JavaScript côté client pour les remplir. Pour en savoir plus sur cette approche, consultez la documentation sur la récupération de données.
Utiliser le rendu côté serveur (SSR) : Next.js pré-rend une page à chaque requête. Ce sera plus lent car la page ne peut pas être mise en cache par un CDN, mais la page pré-rendue sera toujours à jour. Nous parlerons de cette approche ci-dessous.