Dépannage

Astro fournit plusieurs outils différents pour vous aider à dépanner et à déboguer votre code.

Voici une liste de quelques messages d’erreurs courants que vous pourriez rencontrer dans votre terminal, ce qu’ils signifient et ce que vous pouvez faire pour les corriger.

Ce message apparaît souvent à cause d’une limitation actuelle dans Astro qui exige que vos appels import et export soient au début de votre fichier .astro.

Solution: Écrivez vos imports et exports au début de votre Script de composant.

Statut: Limitation actuelle; Un correctif est en cours de développement.

💡 Vous n’êtes pas certain que cela va résoudre votre problème ? Vérifiez si quelqu’un d’autre a déjà signalé ce type d’erreur !

Dans les composants Astro, les balises <script> sont hoistées et chargées comme des modules JavaScript par défaut. Si vous avez ajouté la directive is:inline ou n’importe quel autre attribut dans votre balise, ce comportement par défaut est désactivé.

Solution: Si vous avez ajouté n’importe quel attribut à votre balise <script>, vous devez aussi ajouter la directive type="module" pour pouvoir utiliser les importations.

Statut: Comportement attendu par Astro, comme prévu.

💡 Vous n’êtes pas certain que cela va résoudre votre problème ? Vérifiez si quelqu’un d’autre a déjà signalé ce type d’erreur !

Cette erreur indique une erreur dans un composant que vous avez importé et utilisé dans votre Template de composant Astro.

Ceci peut être causé par l’accès à l’objet window ou document au moment de la génération du composant. Par défaut, Astro génère votre composant isomorphiquement, c’est-à-dire qu’il est exécuté sur le serveur où l’environnement du navigateur n’est pas disponible. Vous pouvez désactiver cette étape de pré-génération en utilisant la directive client:only.

Solution: Essayez d’accéder à ces objets après la génération du composant (ex: useEffect() dans React ou onMounted() dans Vue et Svelte)

Statut: Comportement attendu par Astro, comme prévu.

Solution: Vérifiez la documentation appropriée pour votre composant Astro ou de Framework UI. Vous pouvez aussi ouvrir un Template de démarrage Astro astro.new et déboguer votre composant dans un projet Astro minimal.

💡 Vous n’êtes pas certain que cela va résoudre votre problème ? Vérifiez si quelqu’un d’autre a déjà signalé ce type d’erreur !

Cette erreur peut être levée lorsque vous essayez d’importer ou de rendre un composant invalide, ou un qui ne fonctionne pas correctement. (Ce message d’erreur apparaît car le fonctionnement de l’importation d’un composant UI se fait d’une façon spécifique à Astro.)

Solution: Essayez de trouver des erreurs dans les composants que vous importez et affichez et assurez-vous qu’ils fonctionnent correctement. Vous pouvez aussi ouvrir un Template de démarrage Astro astro.new et déboguer votre composant dans un projet Astro minimal.

Statut: Comportement attendu par Astro, comme prévu.

En premier lieu, vérifiez que vous avez importé le composant dans votre Script de composant .astro ou dans le Frontmatter .md.

Ensuite, vérifiez votre appel import :

• Votre importation dirige-t-elle vers le bon endroit ? (Vérifiez votre chemin d’import.)

• Est-ce que votre importation a le même nom que le composant importé ? (Vérifiez le nom de votre composant et que cela suit la syntaxe .astro.)

• Avez-vous inclu l’extension dans l’importation ? (Vérifiez que le fichier importé contient une extension. Ex: .astro, .md, .jsx, .vue)

Si votre composant est rendu (voir la précédente section) mais ne répond pas à l’interaction utilisateur, alors vous avez peut-être oublié une directive client:* pour hydrater votre composant.

Par défaut, un composants UI de Framework n’est pas hydraté sur le navigateur. Si aucune directive client:* n’est fournie, son HTML est rendu sur la page sans JavaScript.

Note : Les composants Astro sont des composants HTML sans exécution sur le navigateur. Mais, vous pouvez utiliser une balise <script> dans votre Template de composant Astro pour envoyer du JavaScript au navigateur qui s’exécute globalement sur toute la page.

Allez jeter un oeil au guide pour les intégrations Astro pour les instructions sur l’ajout de Framework, des outils CSS et d’autres Packages vers Astro.

Vous pourriez aussi avoir besoin d’installer des “peer dependencies” pour certaines intégrations. Si vous voyez un message « missing peer dependencies », vous pouvez suivre les instructions afin de gérer les dépendances.

Quant vous utilisez Astro.glob() pour importer des fichiers, assurez-vous d’utiliser la syntaxe glob correcte qui va correspondre à tous les fichiers dont vous auriez besoin.

Par exemple, utilisez ../components/**/*.js dans src/pages/index.astro pour importer les deux fichiers suivants :

• src/components/MyComponent.js
• src/components/includes/MyOtherComponent.js

Astro.glob() ne prend pas en charge les variables dynamiques et les interpolations.

Ce n’est pas un bug d’Astro. C’est dû à une limitation de la fonctionnalité import.meta.glob() de Vite qui ne supporte que des chaînes de caractères statiques.

L’alternative la plus courante est d’importer un ensemble plus grand de fichiers qui inclut tous les fichiers dont vous avez besoin en utilisant Astro.glob(), puis de les filtrer :

---
const { postSlug } = Astro.props
const pathToMyFeaturedPost = `src/pages/blog/${postSlug}.md`

const posts = await Astro.glob('../pages/blog/*.md');
const myFeaturedPost = posts.find(post => post.file.includes(pathToMyFeaturedPost));
---

<p>
    Jetez un oeil à mon article favori, <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a> !
</p>

Dans Yarn version 2 ou plus (a.k.a. Berry), utilise une technique appelée “Plug’n’Play” (PnP) pour stocker et gérer les modules Node, qui peut causer des problèmes lors de l’initialisation d’un nouveau projet Astro utilisant create-astro ou lors de l’utilisation de Astro. Une solution est de définir la propriété nodeLinker dans yarnrc.yml à la valeur node-modules :

nodeLinker: "node-modules"

console.log() est un moyen simple mais populaire de déboguer votre code Astro. Lorsque vous écrivez votre appel à console.log, il déterminera où votre sortie de débogage sera affichée.

Un appel à console.log() dans le Frontmatter d’Astro sera toujours sorti dans le terminal qui exécute le processus d’Astro. Car Astro s’exécute sur le serveur, et jamais dans le navigateur.

---
const sum = (a, b) => a + b;

// Exemple : Affiche "4" dans le terminal
console.log(sum(2, 2));
---

Le code qui est écrit ou importé dans un <script> d’Astro sera exécuté dans le navigateur. Toutes les sorties de débogage ou autres appels à console.log() seront affichés dans votre navigateur.

Les composants de Framework (comme React et Svelte) sont uniques : ils sont rendus sur le serveur par défaut, ce qui signifie que les sorties de débogage seront visibles dans le terminal. Cependant, ils peuvent également être hydratés pour le navigateur, ce qui peut aussi entraîner que vos logs de débogage apparaissent également dans le navigateur.

Cela peut être utile pour déboguer les différences entre la sortie SSR et les composants hydratés dans le navigateur.

Pour vous aider à déboguer vos composants Astro, Astro propose un composant <Debug /> (EN) qui affiche directement une valeur dans votre template HTML de composant. Cela est utile pour un débogage rapide dans le navigateur sans avoir à faire les aller-retour entre votre terminal et votre navigateur.

---
import { Debug } from 'astro/components';
const sum = (a, b) => a + b;
---

<!-- Exemple : Affiche {answer: 6} dans le navigateur -->
<Debug answer={sum(2, 4)} />

Le composant <Debug /> d’Astro supporte une variété d’options de syntaxe pour un débogage plus flexible et concis :

---
import { Debug } from 'astro/components';
const sum = (a, b) => a + b;
const answer = sum(2, 4);
---
<!-- Exemple : Les trois exemples sont équivalents. -->
<Debug answer={sum(2, 4)} />
<Debug {{answer: sum(2, 4)}} />
<Debug {answer} />

Venez discuter avec nous sur Discord et expliquez votre problème dans le salon #support. Nous sommes toujours heureux de pouvoir vous aider !

Visitez les “Issues” GitHub ouvertes dans Astro pour voir si vous rencontrez un problème connu ou soumettre un rapport de bug.

Vous pouvez aussi visiter les discussions RFC pour voir si vous avez trouvé une limitation connue d’Astro et regarder si il y a des propositions en rapport avec votre utilisation.