getStaticPaths

Si une page utilise des routes dynamiques et getStaticProps, elle doit définir une liste de chemins à générer statiquement.

Lorsque vous exportez une fonction appelée getStaticPaths (Génération de site statique) depuis une page utilisant des routes dynamiques, Next.js pré-rendra statiquement tous les chemins spécifiés par getStaticPaths.

import type {
  InferGetStaticPropsType,
  GetStaticProps,
  GetStaticPaths,
} from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getStaticPaths = (async () => {
  return {
    paths: [
      {
        params: {
          name: 'next.js',
        },
      }, // Voir la section "paths" ci-dessous
    ],
    fallback: true, // false ou "blocking"
  }
}) satisfies GetStaticPaths

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
}

La référence API de getStaticPaths couvre tous les paramètres et props utilisables avec getStaticPaths.

Quand utiliser getStaticPaths ?

Vous devriez utiliser getStaticPaths si vous pré-rendez statiquement des pages utilisant des routes dynamiques et que :

• Les données proviennent d'un CMS headless
• Les données proviennent d'une base de données
• Les données proviennent du système de fichiers
• Les données peuvent être mises en cache publiquement (non spécifiques à un utilisateur)
• 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

Quand getStaticPaths s'exécute-t-il ?

getStaticPaths ne s'exécute que lors de la construction en production, il n'est pas appelé pendant l'exécution. Vous pouvez vérifier que le code écrit dans getStaticPaths est retiré du bundle côté client avec cet outil.

Comment getStaticProps s'exécute-t-il par rapport à getStaticPaths

• getStaticProps s'exécute pendant next build pour tous les paths retournés lors de la construction
• getStaticProps s'exécute en arrière-plan quand fallback: true est utilisé
• getStaticProps est appelé avant le rendu initial quand fallback: blocking est utilisé

Où utiliser getStaticPaths

• getStaticPaths doit être utilisé avec getStaticProps
• Vous ne pouvez pas utiliser getStaticPaths avec getServerSideProps
• Vous pouvez exporter getStaticPaths depuis une route dynamique qui utilise aussi getStaticProps
• Vous ne pouvez pas exporter getStaticPaths depuis un fichier non-page (ex. votre dossier components)
• Vous devez exporter getStaticPaths comme une fonction autonome, et non comme une propriété du composant de page

S'exécute à chaque requête en développement

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

Génération de chemins à la demande

getStaticPaths vous permet de contrôler quelles pages sont générées pendant la construction plutôt qu'à la demande avec fallback. Générer plus de pages pendant la construction ralentira les builds.

Vous pouvez différer la génération de toutes les pages à la demande en retournant un tableau vide pour paths. Ceci peut être particulièrement utile lors du déploiement de votre application Next.js dans plusieurs environnements. Par exemple, vous pouvez avoir des builds plus rapides en générant toutes les pages à la demande pour les prévisualisations (mais pas pour les builds de production). Ceci est utile pour les sites avec des centaines/milliers de pages statiques.

export async function getStaticPaths() {
  // Quand ceci est vrai (dans les environnements de prévisualisation)
  // ne pré-rendez aucune page statique
  // (builds plus rapides, mais chargement initial de page plus lent)
  if (process.env.SKIP_BUILD_STATIC_GENERATION) {
    return {
      paths: [],
      fallback: 'blocking',
    }
  }

  // Appelez un endpoint API externe pour obtenir les posts
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // Obtenez les chemins à pré-rendre basés sur les posts
  // Dans les environnements de production, pré-rendez toutes les pages
  // (builds plus lents, mais chargement initial de page plus rapide)
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  // { fallback: false } signifie que les autres routes renverront une 404
  return { paths, fallback: false }
}