getStaticPaths

Lorsque vous exportez une fonction appelée getStaticPaths 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
}

Valeurs de retour de getStaticPaths

La fonction getStaticPaths doit retourner un objet avec les propriétés requises suivantes :

paths

La clé paths détermine quels chemins seront pré-rendus. Par exemple, supposons que vous ayez une page utilisant des routes dynamiques nommée pages/posts/[id].js. Si vous exportez getStaticPaths depuis cette page et retournez ce qui suit pour paths :

return {
  paths: [
    { params: { id: '1' }},
    {
      params: { id: '2' },
      // avec i18n configuré, la locale pour le chemin peut également être retournée
      locale: "en",
    },
  ],
  fallback: ...
}

Ensuite, Next.js générera statiquement /posts/1 et /posts/2 pendant next build en utilisant le composant de page dans pages/posts/[id].js.

La valeur de chaque objet params doit correspondre aux paramètres utilisés dans le nom de la page :

• Si le nom de la page est pages/posts/[postId]/[commentId], alors params doit contenir postId et commentId.
• Si la page utilise des routes catch-all comme pages/[...slug], alors params doit contenir slug (qui est un tableau). Si ce tableau est ['hello', 'world'], alors Next.js générera statiquement la page à /hello/world.
• Si la page utilise une route catch-all optionnelle, utilisez null, [], undefined ou false pour rendre la route racine. Par exemple, si vous fournissez slug: false pour pages/[[...slug]], Next.js générera statiquement la page /.

Les chaînes params sont sensibles à la casse et idéalement devraient être normalisées pour garantir que les chemins sont générés correctement. Par exemple, si WoRLD est retourné pour un paramètre, cela ne correspondra que si WoRLD est le chemin réellement visité, pas world ou World.

Séparément de l'objet params, un champ locale peut être retourné lorsque i18n est configuré, ce qui configure la locale pour le chemin généré.

fallback: false

Si fallback est false, tout chemin non retourné par getStaticPaths résultera en une page 404.

Lorsque next build est exécuté, Next.js vérifiera si getStaticPaths a retourné fallback: false, puis construira uniquement les chemins retournés par getStaticPaths. Cette option est utile si vous avez un petit nombre de chemins à créer ou si les données de nouvelles pages ne sont pas ajoutées souvent. Si vous devez ajouter plus de chemins et que vous avez fallback: false, vous devrez exécuter next build à nouveau pour que les nouveaux chemins puissent être générés.

L'exemple suivant pré-rend un article de blog par page appelé pages/posts/[id].js. La liste des articles de blog sera récupérée depuis un CMS et retournée par getStaticPaths. Ensuite, pour chaque page, il récupère les données de l'article depuis un CMS en utilisant getStaticProps.

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

// Cette fonction est appelée au moment de la construction
export async function getStaticPaths() {
  // Appeler une 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 renverront une 404.
  return { paths, fallback: false }
}

// Ceci est également appelé 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 } }
}

export default Post

fallback: true

Si fallback est true, le comportement de getStaticProps change de la manière suivante :

• Les chemins retournés par getStaticPaths seront rendus en HTML au moment de la construction par getStaticProps.
• Les chemins qui n'ont pas été générés au moment de la construction ne renverront pas une page 404. À la place, Next.js servira une version de « fallback » de la page lors de la première requête vers ce chemin. Les robots d'indexation, comme Google, ne recevront pas de fallback et le chemin se comportera comme avec fallback: 'blocking'.
• Lorsqu'une page avec fallback: true est atteinte via next/link ou next/router (côté client), Next.js ne servira pas de fallback et la page se comportera comme avec fallback: 'blocking'.
• En arrière-plan, Next.js générera statiquement le HTML et JSON du chemin demandé. Cela inclut l'exécution de getStaticProps.
• Une fois terminé, le navigateur recevra le JSON pour le chemin généré. Ceci sera utilisé pour rendre automatiquement la page avec les props requises. Du point de vue de l'utilisateur, la page passera de la page de fallback à la page complète.
• En même temps, Next.js ajoute ce chemin à la liste des pages pré-rendues. Les requêtes suivantes vers le même chemin serviront la page générée, comme les autres pages pré-rendues au moment de la construction.

Bon à savoir : fallback: true n'est pas supporté lors de l'utilisation de output: 'export'.

Quand fallback: true est-il utile ?

fallback: true est utile si votre application a un très grand nombre de pages statiques dépendant de données (comme un très grand site e-commerce). Si vous voulez pré-rendre toutes les pages de produits, les constructions prendraient très longtemps.

À la place, vous pouvez générer statiquement un petit sous-ensemble de pages et utiliser fallback: true pour le reste. Lorsque quelqu'un demande une page qui n'a pas encore été générée, l'utilisateur verra la page avec un indicateur de chargement ou un composant squelette.

Peu après, getStaticProps se termine et la page sera rendue avec les données demandées. Désormais, toute personne demandant la même page recevra la page pré-rendue statiquement.

Cela garantit que les utilisateurs ont toujours une expérience rapide tout en préservant des constructions rapides et les bénéfices de la génération statique.

fallback: true ne mettra pas à jour les pages générées, pour cela, consultez la régénération statique incrémentielle.

fallback: 'blocking'

Si fallback est 'blocking', les nouveaux chemins non retournés par getStaticPaths attendront que le HTML soit généré, identique au SSR (d'où le terme blocking), puis seront mis en cache pour les requêtes futures afin que cela n'arrive qu'une fois par chemin.

getStaticProps se comportera comme suit :

• Les chemins retournés par getStaticPaths seront rendus en HTML au moment de la construction par getStaticProps.
• Les chemins qui n'ont pas été générés au moment de la construction ne renverront pas une page 404. À la place, Next.js fera du SSR lors de la première requête et retournera le HTML généré.
• Une fois terminé, le navigateur recevra le HTML pour le chemin généré. Du point de vue de l'utilisateur, cela passera de "le navigateur demande la page" à "la page entière est chargée". Il n'y a pas d'affichage flash d'état de chargement/fallback.
• En même temps, Next.js ajoute ce chemin à la liste des pages pré-rendues. Les requêtes suivantes vers le même chemin serviront la page générée, comme les autres pages pré-rendues au moment de la construction.

fallback: 'blocking' ne mettra pas à jour les pages générées par défaut. Pour mettre à jour les pages générées, utilisez la régénération statique incrémentielle conjointement avec fallback: 'blocking'.

Bon à savoir : fallback: 'blocking' n'est pas supporté lors de l'utilisation de output: 'export'.

Pages de fallback

Dans la version "fallback" d'une page :

• Les props de la page seront vides.
• En utilisant le routeur, vous pouvez détecter si le fallback est en cours de rendu, router.isFallback sera true.

L'exemple suivant montre l'utilisation de isFallback :

import { useRouter } from 'next/router'

function Post({ post }) {
  const router = useRouter()

  // Si la page n'est pas encore générée, ceci sera affiché
  // initialement jusqu'à ce que getStaticProps() termine son exécution
  if (router.isFallback) {
    return <div>Chargement...</div>
  }

  // Afficher l'article...
}

// Cette fonction est appelée au moment de la construction
export async function getStaticPaths() {
  return {
    // Seuls `/posts/1` et `/posts/2` sont générés au moment de la construction
    paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
    // Activer la génération statique de pages supplémentaires
    // Par exemple : `/posts/3`
    fallback: true,
  }
}

// Ceci est également appelé 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 },
    // Régénérer l'article au maximum une fois par seconde
    // si une requête arrive
    revalidate: 1,
  }
}

export default Post

Historique des versions