Concepts avancés

Erreurs

Les erreurs sont inévitables dans le développement logiciel. SvelteKit gère les erreurs différemment selon l'endroit où elles se produisent, leur type, et la nature de la requête entrante.

Les objets d'erreurpermalink

SvelteKit différencie les erreurs attendues et inattendues, les deux étant représentées comme de simples objets { message: string } par défaut.

Vous pouvez ajouter des propriétés supplémentaires, comme un code ou un id de suivi, comme montré dans les exemples ci-dessous. (Lorsque vous utilisez TypeScript, ceci requiert que vous redéfinissiez le type Error comme décrit dans la section sur le typage).

Erreurs attenduespermalink

Une erreur attendue est une erreur créée avec l'utilitaire error importé depuis @sveltejs/kit :

src/routes/blog/[slug]/+page.server.js

ts
import { error } from '@sveltejs/kit';
import * as db from '$lib/server/database';

/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
	const post = await db.getPost(params.slug);

	if (!post) {
		error(404, {
			message: 'Introuvable'
		});
	}

	return { post };
}

src/routes/blog/[slug]/+page.server.ts

ts
import { error } from '@sveltejs/kit';
import * as db from '$lib/server/database';
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ params }) => {
	const post = await db.getPost(params.slug);

	if (!post) {
		error(404, {
			message: 'Introuvable',
		});
	}

	return { post };
};

Ceci lève une exception que SvelteKit va attraper, ce qui aura pour conséquence de définir le statut de la réponse à 404 et de rendre un composant +error.svelte, où $page.error est l'objet fourni comme second argument à error(...).

src/routes/+error.svelte

<script>
	import { page } from '$app/stores';
</script>

<h1>{$page.error.message}</h1>

src/routes/+error.svelte

<script lang="ts">
	import { page } from '$app/stores';
</script>

<h1>{$page.error.message}</h1>

Vous pouvez ajouter des propriétés supplémentaires à l'objet d'erreur si besoin...

error(404, {
	message: 'Introuvable',
	code: 'NOT_FOUND'
});

...ou sinon, par commodité, vous pouvez fournir une chaîne de caractères en deuxième argument :

error(404, { message: 'Not found' });
error(404, 'Introuvable');

Avec SvelteKit 1.x, vous deviez lever une exception avec le retour de la méthode error vous-même.

Erreurs inattenduespermalink

Une erreur inattendue est toute autre exception qui se produit pendant qu'une requête est traitée. Puisqu'ils peuvent contenir des informations sensibles, les messages des erreurs inattendues et leur stack trace ne sont pas exposés aux utilisateurs et utilisatrices.

Par défaut, les erreurs inattendues sont affichées dans la console, (ou, en production, dans vos logs de serveur), tandis que l'erreur exposée dans le client a la forme générique suivante :

ts
{ "message": "Internal Error" }

Les erreurs inattendues passent par le hook handleError, où vous pouvez ajouter votre propre gestion d'erreur – par exemple envoyer les erreurs à un service de suivi, ou renvoyer au client un objet d'erreur personnalisé qui devient $page.error.

Réponsespermalink

Si une erreur se produit dans handle ou dans un endpoint de +server.js, SvelteKit répondra avec soit une page d'erreur par défaut, soit une représentation JSON de l'objet d'erreur, en fonction des headers Accept de la requête.

Vous pouvez personnaliser la page d'erreur par défaut en ajoutant un fichier src/error.html :

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>%sveltekit.error.message%</title>
	</head>
	<body>
		<h1>Ma page d'erreur par défaut</h1>
		<p>Statut: %sveltekit.status%</p>
		<p>Message: %sveltekit.error.message%</p>
	</body>
</html>

SvelteKit va remplacer %sveltekit.status% et %sveltekit.error.message% par leurs valeurs respectives.

Si au contraire une erreur se produit dans une fonction load lors d'un rendu de page, SvelteKit va rendre le composant [+error.svelte] le plus proche de là où l'erreur s'est produite. Si l'erreur se produit dans une fonction load d'un +layout(.server).js, le fichier d'erreur le plus proche dans l'arborescence sera un fichier +error.svelte au-dessus de ce layout (et pas au même niveau).

L'exception à cette règle est lorsque l'erreur se produit dans le fichier +layout.js ou +layout.server.js racine, puisque le layout racine contient en général le composant +error.svelte. Dans ce cas, SvelteKit affichera la page d'erreur par défaut.

Typagepermalink

Si vous utilisez TypeScript et avez besoin de personnaliser la forme de vos erreurs, vous pouvez le faire en déclarant une interface App.Error dans votre application (par convention, dans src/app.d.ts, même s'elle peut se trouver dans n'importe fichier que TypeScript peut "voir") :

src/app.d.ts

declare global {
	namespace App {
		interface Error {
			code: string;
			id: string;
		}
	}
}

export {};

Cette interface incluera toujours une propriété message: string.