Guide source maps

Source maps : retrouver votre code dans les stack traces

En production, une erreur pointe vers page-3f2a.js, ligne 1, colonne 18204. Avec vos source maps, Errilo affiche le fichier, la ligne et la fonction d’origine, avec le code autour de l’erreur. L’envoi se fait au build, avec les outils Sentry que vous utilisez déjà.

Mis à jour le

Errilo est en développement. Ce guide décrit la configuration que notre suite de compatibilité teste aujourd’hui ; la bêta privée ouvre à l’été 2027.

Comment ça marche

Au build, chaque fichier JavaScript reçoit un debug ID : un identifiant unique écrit dans le fichier et dans sa source map. Le plugin de build Sentry envoie ensuite les fichiers et leurs source maps à Errilo. Quand une erreur arrive, ses frames portent ces debug IDs : Errilo retrouve la bonne source map sans dépendre d’un nom de release.

Les frames sont traduites à la réception de l’erreur, avant son enregistrement : fichier, ligne, colonne et fonction d’origine, plus cinq lignes de code avant et après. Les issues sont regroupées sur le code d’origine : la même erreur venue de deux builds différents tombe dans la même issue.

Un debug ID n’est cherché que dans le projet qui a reçu les source maps, jamais d’un projet à l’autre.

1. Créer un jeton

Dans Errilo, ouvrez Paramètres, section Jetons d’API, puis Nouveau jeton, et cochez la portée project:releases (« Gérer les releases »). Limitez-le au projet concerné : c’est tout ce dont une CI a besoin.

Le jeton (errilo_…) n’est affiché qu’une fois : rangez-le tout de suite dans les secrets de votre CI. Sans la portée project:releases, l’envoi est refusé avec une erreur 403.

2. Définir les variables du build

Le plugin de build Sentry lit quatre variables dans l’environnement du build :

Variables lues par le plugin de build Sentry
VariableValeur
SENTRY_URLL’adresse de l’application Errilo, https://app.errilo.com/, et non celle de l’ingestion des événements
SENTRY_ORGLe slug de votre organisation
SENTRY_PROJECTLe slug du projet qui reçoit les erreurs, celui dont votre app utilise le DSN
SENTRY_AUTH_TOKENLe jeton de l’étape 1
.env (CI)
SENTRY_URL=https://app.errilo.com/
SENTRY_ORG=<votre-organisation-errilo>
SENTRY_PROJECT=<votre-projet-errilo>
SENTRY_AUTH_TOKEN=errilo_...

Ne commitez jamais SENTRY_AUTH_TOKEN et ne l’exposez jamais au navigateur : pas de préfixe NEXT_PUBLIC_.

3. Next.js : rien à configurer

@sentry/nextjs fait tout pendant le next build : il écrit les debug IDs, envoie les source maps du serveur et du navigateur, et crée la release. Votre next.config.js garde sa configuration Sentry habituelle, sans organisation, projet, jeton ni URL (le reste de l’installation est dans le guide Next.js) :

next.config.js
// SDK 9 : require("@sentry/nextjs")
const { withSentryConfig } = require("@sentry/nextjs/config");

module.exports = withSentryConfig({
  // votre configuration Next.js
});

Lancez ensuite le build avec les quatre variables dans son environnement :

CI
# SENTRY_AUTH_TOKEN vient des secrets de votre CI
export SENTRY_URL=https://app.errilo.com/
export SENTRY_ORG=mon-organisation
export SENTRY_PROJECT=mon-projet
pnpm build

Notre suite de compatibilité construit une app Next.js 15 de production avec chaque version ci-dessous, envoie ses source maps avec le plugin et ces seules variables, puis vérifie qu’une erreur serveur et une erreur navigateur arrivent avec leur fichier, leur ligne et leur code d’origine.

Versions de @sentry/nextjs testées contre Errilo
Version majeureVersion testée
v9@sentry/[email protected]
v10@sentry/[email protected]
v11@sentry/[email protected]

4. Autres outils de build : sentry-cli

Bientôt : notre suite de compatibilité ne vérifie pas encore l’envoi avec sentry-cli (Vite, Nuxt, SvelteKit, webpack, esbuild…).

Pour toute autre app JavaScript, générez les source maps au build, puis lancez sentry-cli sur le dossier construit, avec les quatre mêmes variables :

CI
sentry-cli sourcemaps inject ./dist
sentry-cli sourcemaps upload ./dist

Quand une frame reste minifiée

L’erreur est toujours enregistrée, avec ses frames minifiées. La page de l’issue affiche « La symbolication a échoué pour N fichiers », avec pour chaque fichier son chemin, son debug ID et l’une de ces causes :

Erreurs de symbolication et points à vérifier
MessageÀ vérifier
« Aucune source map n’a été envoyée pour ce fichier. »L’envoi a-t-il réussi (sortie du plugin, jeton valide) ? SENTRY_PROJECT est-il le projet dont le DSN reçoit les erreurs ? Le fichier servi est-il celui qui a été envoyé ? L’erreur est-elle arrivée après le traitement de l’envoi ?
« La source map de ce fichier est illisible ou trop volumineuse. »Une source map fait 32 Mio au plus. Vérifiez que l’envoi contient bien le fichier .map et que c’est du JSON valide.
« La position de la frame n’existe pas dans la source map. »Le fichier a été modifié après la génération de sa source map (bannière ajoutée, second minifieur). Générez la map en dernier, puis injectez, puis envoyez.

Frames traduites mais sans code autour : la source map n’a pas de sourcesContent. Activez-le dans votre outil de build ; la plupart le font par défaut.

L’envoi lui-même échoue :

Limites connues

Accès anticipé

Nous ouvrons une bêta privée à l’été 2027 pour quelques équipes qui font tourner Node.js ou TypeScript en production. Inscrivez-vous sur la liste d’attente : nous vous écrirons à l’ouverture.