Gestion des erreurs

La convention de fichier error.js vous permet de gérer élégamment les erreurs d'exécution inattendues dans les routes imbriquées.

• Englobe automatiquement un segment de route et ses enfants dans une limite d'erreur React (React Error Boundary).
• Créez une interface d'erreur adaptée à des segments spécifiques en utilisant la hiérarchie du système de fichiers pour ajuster la granularité.
• Isolez les erreurs aux segments affectés tout en gardant le reste de l'application fonctionnelle.
• Ajoutez des fonctionnalités pour tenter de récupérer d'une erreur sans rechargement complet de la page.

Créez une interface d'erreur en ajoutant un fichier error.js à l'intérieur d'un segment de route et en exportant un composant React :

'use client' // Les composants d'erreur doivent être des composants clients

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Enregistrez l'erreur dans un service de rapport d'erreurs
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Quelque chose s'est mal passé !</h2>
      <button
        onClick={
          // Tentez de récupérer en re-rendant le segment
          () => reset()
        }
      >
        Réessayer
      </button>
    </div>
  )
}

'use client' // Les composants d'erreur doivent être des composants clients

import { useEffect } from 'react'

export default function Error({ error, reset }) {
  useEffect(() => {
    // Enregistrez l'erreur dans un service de rapport d'erreurs
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Quelque chose s'est mal passé !</h2>
      <button
        onClick={
          // Tentez de récupérer en re-rendant le segment
          () => reset()
        }
      >
        Réessayer
      </button>
    </div>
  )
}

Fonctionnement de error.js

• error.js crée automatiquement une limite d'erreur React (React Error Boundary) qui englobe un segment enfant imbriqué ou un composant page.js.
• Le composant React exporté depuis le fichier error.js est utilisé comme composant de secours (fallback).
• Si une erreur est levée dans la limite d'erreur, l'erreur est contenue et le composant de secours est affiché.
• Lorsque le composant d'erreur de secours est actif, les mises en page au-dessus de la limite d'erreur conservent leur état et restent interactives, et le composant d'erreur peut afficher des fonctionnalités pour récupérer de l'erreur.

Récupération après une erreur

La cause d'une erreur peut parfois être temporaire. Dans ces cas, un simple réessai peut résoudre le problème.

Un composant d'erreur peut utiliser la fonction reset() pour inviter l'utilisateur à tenter de récupérer de l'erreur. Lorsqu'elle est exécutée, la fonction tentera de re-rendre le contenu de la limite d'erreur. Si cela réussit, le composant d'erreur de secours est remplacé par le résultat du re-rendu.

'use client'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>Quelque chose s'est mal passé !</h2>
      <button onClick={() => reset()}>Réessayer</button>
    </div>
  )
}

'use client'

export default function Error({ error, reset }) {
  return (
    <div>
      <h2>Quelque chose s'est mal passé !</h2>
      <button onClick={() => reset()}>Réessayer</button>
    </div>
  )
}

Routes imbriquées

Les composants React créés via des fichiers spéciaux sont rendus dans une hiérarchie imbriquée spécifique.

Par exemple, une route imbriquée avec deux segments incluant chacun des fichiers layout.js et error.js est rendue dans la hiérarchie de composants simplifiée suivante :

La hiérarchie de composants imbriqués a des implications sur le comportement des fichiers error.js dans une route imbriquée :

• Les erreurs remontent à la limite d'erreur parente la plus proche. Cela signifie qu'un fichier error.js gérera les erreurs pour tous ses segments enfants imbriqués. Une interface d'erreur plus ou moins granulaire peut être obtenue en plaçant des fichiers error.js à différents niveaux dans les dossiers imbriqués d'une route.
• Une limite error.js ne gérera pas les erreurs levées dans un composant layout.js du même segment, car la limite d'erreur est imbriquée à l'intérieur du composant de mise en page.

Gestion des erreurs dans les mises en page

Les limites error.js ne capturent pas les erreurs levées dans les composants layout.js ou template.js du même segment. Cette hiérarchie intentionnelle permet de garder visible et fonctionnelle l'interface utilisateur partagée entre les routes sœurs (comme la navigation) lorsqu'une erreur se produit.

Pour gérer les erreurs dans une mise en page ou un modèle spécifique, placez un fichier error.js dans le segment parent de la mise en page.

Pour gérer les erreurs dans la mise en page racine ou le modèle, utilisez une variante de error.js appelée global-error.js.

Gestion des erreurs dans les mises en page racines

La limite app/error.js racine ne capture pas les erreurs levées dans le composant app/layout.js ou app/template.js racine.

Pour gérer spécifiquement les erreurs dans ces composants racines, utilisez une variante de error.js appelée app/global-error.js située dans le répertoire racine app.

Contrairement à error.js racine, la limite d'erreur global-error.js englobe l'ensemble de l'application, et son composant de secours remplace la mise en page racine lorsqu'il est actif. Pour cette raison, il est important de noter que global-error.js doit définir ses propres balises <html> et <body>.

global-error.js est l'interface d'erreur la moins granulaire et peut être considérée comme une gestion d'erreur "tout compris" pour toute l'application. Il est peu probable qu'elle soit déclenchée souvent, car les composants racines sont généralement moins dynamiques, et d'autres limites error.js captureront la plupart des erreurs.

Même si un global-error.js est défini, il est toujours recommandé de définir un error.js racine dont le composant de secours sera affiché dans la mise en page racine, qui inclut l'interface utilisateur et l'identité visuelle partagées globalement.

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Quelque chose s'est mal passé !</h2>
        <button onClick={() => reset()}>Réessayer</button>
      </body>
    </html>
  )
}

'use client'

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h2>Quelque chose s'est mal passé !</h2>
        <button onClick={() => reset()}>Réessayer</button>
      </body>
    </html>
  )
}

Bon à savoir :

• global-error.js n'est activé qu'en production. En développement, notre superposition d'erreur s'affichera à la place.

Gestion des erreurs serveur

Si une erreur est levée dans un composant serveur, Next.js transmettra un objet Error (dépouillé des informations sensibles en production) au fichier error.js le plus proche en tant que prop error.

Sécurisation des informations sensibles d'erreur

En production, l'objet Error transmis au client ne comprend qu'une propriété générique message et une propriété digest.

Il s'agit d'une précaution de sécurité pour éviter de divulguer des détails potentiellement sensibles inclus dans l'erreur au client.

La propriété message contient un message générique sur l'erreur et la propriété digest contient un hachage généré automatiquement de l'erreur qui peut être utilisé pour correspondre à l'erreur correspondante dans les journaux côté serveur.

En développement, l'objet Error transmis au client sera sérialisé et inclura le message de l'erreur originale pour faciliter le débogage.