Gestion des erreurs

Les erreurs Vincle portent un code stable permettant de distinguer leur origine et de les traiter.

Erreurs globales#

Capturez les erreurs autour de la construction JSX et de l’appel attendu au renderer : certaines validations échouent immédiatement, d’autres durant le rendu asynchrone.

import { renderToString } from "@vincle/core";

try {
  const html = await renderToString(<Page />);
  // send html to client
} catch (error) {
  console.error("Page render failed:", error);
  // send a 500 or fallback page
}

Format des messages#

Le message indique la cause et, lorsque c’est possible, le composant concerné. Utilisez error.code pour la logique applicative plutôt que de comparer le texte du message.

[vincle/<package>] <api or component>: <what happened>. <why>. <how to fix it>

[vincle/flow] <Defer target="hero">: merge="prepend" is not supported by this adapter: it supports: replace, append. Pick one of those, or use an adapter that supports "prepend".

Codes d’erreur#

Les codes publics couvrent les erreurs de rendu, de fragments et de configuration. Les exemples ci-dessous montrent comment les vérifier.

try {
  html = await renderToString(<Page />);
} catch (error) {
  if (error.code === "ERR_VINCLE_VOID_CHILDREN") {
    // the markup is wrong, not the data
  }
}

@vincle/core#

Core signale notamment les balises invalides, le contenu d’un élément vide, les fonctions utilisées comme attributs et les clés de contexte absentes.

@vincle/flow#

Flow signale les identifiants de fragments invalides, les incohérences de configuration, les délais dépassés et les erreurs de contenu différé.

@vincle/vite-plugin et @vincle/precompile#

Les outils de build signalent les configurations invalides, les manifestes illisibles ou mal formés et les imports de runtime invalides.

Erreurs par fragment (streaming)#

En streaming, une erreur dans un fragment peut être traitée par onError(error, id) sans abandonner tout le document. Choisissez un remplacement qui n’expose aucune information sensible.

serve(req, () => <Page />, NativeAdapter, {
  onError: (error, { id, kind }) => {
    console.error(`Fragment ${id} failed:`, error);
    return <p>This section failed to load.</p>;
  },
});