Gérer les erreurs comme un pro dans Nuxt 3 : Guide complet

Introduction

Dans toute application web, les erreurs sont inévitables :

• un appel API qui échoue,

• un utilisateur qui tape une URL inexistante,

• un serveur qui retourne une erreur 500.

Avec Nuxt 3, la gestion des erreurs a été simplifiée grâce à des outils puissants comme :
1. showError()
2. useError()
3. createError()
4. et les pages d’erreurs personnalisées.

Dans cet article, on va voir comment les utiliser pour :
1. Créer une expérience utilisateur fluide même en cas d’erreur.
2. Éviter les crashs imprévus côté serveur et client.
3. Proposer des pages d’erreur élégantes et utiles.

1. Les outils de gestion d’erreurs dans Nuxt 3

Nuxt 3 fournit 3 fonctions principales pour gérer les erreurs :

2. Déclencher une erreur avec showError()

Quand une action côté client échoue, utilise showError pour rediriger automatiquement vers la page d’erreur.

Exemple : appel API dans une page

<script setup>
const { data, error } = await useFetch('/api/posts')

if (error.value) {
  showError({
    statusCode: 404,
    statusMessage: 'Articles introuvables.'
  })
}
</script>

Ici, si l’API renvoie une erreur, l’utilisateur sera redirigé vers la page /error avec le code et le message fournis.

3. Récupérer les erreurs avec useError()

Sur la page d’erreur (error.vue), tu peux récupérer les détails avec useError() :

<template>
  <div class="error-page">
    <h1>Oups 😥 Erreur {{ error.statusCode }}</h1>
    <p>{{ error.statusMessage }}</p>
    <NuxtLink to="/" class="btn">Retour à l’accueil</NuxtLink>
  </div>
</template>

<script setup>
const error = useError()
</script>

4. Générer des erreurs personnalisées avec createError()

Pourquoi createError() ?

C’est la fonction à utiliser côté serveur (dans des API ou middlewares) pour envoyer une réponse d’erreur propre à Nuxt.

Exemple : dans une API

// server/api/posts.ts
export default defineEventHandler(async (event) => {
  const posts = await fetchPostsFromDB()

  if (!posts.length) {
    throw createError({
      statusCode: 404,
      statusMessage: 'Aucun article trouvé.'
    })
  }

  return posts
})

Ici, si la base de données ne retourne aucun article, l’API renverra une erreur HTTP 404 avec un message explicite.

Exemple : middleware de protection

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const isAuthenticated = false // Supposons l’utilisateur non connecté

  if (!isAuthenticated) {
    throw createError({
      statusCode: 401,
      statusMessage: 'Accès refusé : veuillez vous connecter.'
    })
  }
})

L’utilisateur non connecté sera redirigé vers la page d’erreur avec le code 401.

5. Créer une page d’erreurs personnalisée

Pour améliorer l’expérience utilisateur, crée un fichier error.vue dans /error :

<template>
  <div class="error-page">
    <h1>Erreur {{ error.statusCode }}</h1>
    <p>{{ error.statusMessage }}</p>
    <NuxtLink to="/" class="btn">Retour à l’accueil</NuxtLink>
  </div>
</template>

<script setup>
const error = useError()
</script>

<style scoped>
.error-page {
  text-align: center;
  margin-top: 50px;
}
h1 {
  font-size: 3rem;
  color: #42b883;
}
p {
  margin: 20px 0;
}
.btn {
  background: #42b883;
  color: white;
  padding: 10px 20px;
  border-radius: 8px;
  text-decoration: none;
}
</style>

Conclusion

Avec showError, useError, et createError, Nuxt 3 te donne toutes les clés pour :

• Attraper les erreurs côté client et serveur,

• Fournir des messages explicites,

• Et créer des pages d’erreur élégantes.

Une bonne gestion des erreurs améliore la qualité et la confiance dans ton application.