Dépannage

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

Trucs et astuces

Débogage avec `console.log()`

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.

---
console.log('Salut ! Je suis le serveur. Ceci est affiché dans le terminal où Astro est exécuté.');
---

<script>
console.log('Salut ! Je suis le client. Ceci est affiché dans la console de développement du navigateur.');
</script>

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.

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.

Débogage des composants de Framework

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 serveur et les composants hydratés dans le navigateur.

Le composant `<Debug />` d’Astro

Pour vous aider à déboguer vos composants Astro, Astro propose un composant <Debug /> qui affiche directement une valeur dans votre template HTML de composant.

Ce composant permet d’inspecter des valeurs du côté client, sans JavaScript. Il peut être utile pour un débogage rapide dans le navigateur, sans avoir à passer d’un terminal à l’autre.

---
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 prend en charge une variété d’options syntaxiques pour un débogage encore plus souple 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} />

Erreurs courantes

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.

Cannot use import statement outside a module

Dans les composants Astro, les balises <script> sont 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 sûr qu’il s’agisse de votre problème ? Vérifiez si quelqu’un d’autre a déjà signalé ce type d’erreur !

`document` (or `window`) is not defined

Cette erreur se produit lorsqu’on essaie d’accéder à document ou window sur le serveur.

Les composants Astro fonctionnent sur le serveur, vous ne pouvez donc pas accéder à ces objets spécifiques au navigateur dans le frontmatter.

Les composants des Frameworks s’exécutent par défaut sur le serveur, et cette erreur peut donc se produire lors de l’accès à document ou window pendant le rendu.

Solution : Déterminez le code qui appelle document ou window. Si vous n’utilisez pas directement document ou window et que vous obtenez toujours cette erreur, vérifiez si les packages que vous importez sont destinés à fonctionner sur le client.

Si le code se trouve dans un composant Astro, déplacez-le dans une balise <script> à l’extérieur du frontmatter. Cela indique à Astro d’exécuter ce code sur le client, où document et window sont disponibles.
Si le code est dans un composant du framework, essayez d’accéder à ces objets après le rendu en utilisant des méthodes de cycle de vie (par exemple useEffect() dans React, onMounted() dans Vue, et onMount() dans Svelte). Indiquez au composant du framework de s’hydrater côté client en utilisant une directive client :, comme client:load, pour exécuter ces méthodes de cycle de vie. Vous pouvez également empêcher le composant d’effectuer un rendu sur le serveur en ajoutant la directive client:only.

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

Expected a default export

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.

Refused to execute inline script

Il se peut que l’erreur suivante apparaisse dans la console du navigateur :

Refused to execute inline script because it violates the following Content Security Policy directive: …

Cela signifie que la Content Security Policy (CSP) de votre site interdit l’exécution des balises <script>, qu’Astro produit par défaut.

Solution : Mettez à jour votre CSP pour inclure script-src : 'unsafe-inline' afin d’autoriser l’exécution des scripts inline. Vous pouvez également utiliser une intégration tierce telle que astro-shield pour générer les en-têtes CSP pour vous.

Problèmes courants

Mon composant ne s’affiche pas

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

Ensuite, vérifiez votre appel import :

Votre importation dirige-t-elle vers le bon endroit ? (Vérifiez votre chemin d’import.)
Votre import a-t-il le même nom que le composant importé ? (Vérifiez le nom de votre composant et qu’il respecte la syntaxe .astro.)
Avez-vous inclus l’extension dans l’importation ? (Vérifiez que votre fichier importé contient une extension, par exemple .astro, .md, .vue, .svelte. Note : Les extensions de fichiers sont optionnelles pour les fichiers .js(x) et .ts(x)).

Mon composant n’est pas interactif

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 composant 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.

Cannot find package ‘X’

Si vous voyez un avertissement du type "Cannot find package 'react'" (ou similaire) lorsque vous démarrez Astro, cela signifie que vous devez installer ce package dans votre projet. Tous les gestionnaires de packages n’installent pas automatiquement les dépendances pour vous. Si vous êtes sur Node v16+ et que vous utilisez npm, vous ne devriez pas avoir à vous soucier de cette section.

React, par exemple, est une dépendance peer de l’intégration @astrojs/react. Cela signifie que vous devez installer les packages officiels react et react-dom avec votre intégration. L’intégration s’appuiera alors automatiquement sur ces packages.

# Exemple : Installer les intégrations et les frameworks ensemble
npm install @astrojs/react react-dom

Voir le guide d’intégration d’Astro pour des instructions sur l’ajout de moteurs de rendu de frameworks, d’outils CSS et d’autres packages à Astro.

Utilisation d’Astro avec Yarn 2+ (Berry)

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"

Ajouter des dépendances à Astro dans une monorepo

Lorsque vous travaillez avec Astro dans une configuration monorepo, les dépendances du projet doivent être ajoutées dans le fichier package.json de chaque projet.

Cependant, vous pouvez aussi vouloir utiliser Astro à la racine de la monorepo (par exemple, les projets Nx recommandent d’installer les dépendances à la racine). Dans ce cas, ajoutez manuellement les dépendances liées à Astro (par exemple @astrojs/vue, astro-component-lib) à la partie vite.ssr.noExternal de la configuration d’Astro pour vous assurer que ces dépendances sont correctement installées et regroupées :

import { defineConfig } from 'astro/config'
export default defineConfig({
  vite: {
    ssr: {
      noExternal: [
        '@astrojs/vue',
        'astro-component-lib',
      ]
    }
  }
})

Utilisation de `<head>` dans un composant

Dans Astro, l’utilisation d’une balise <head> fonctionne comme n’importe quelle autre balise HTML : elle n’est pas déplacée en haut de la page ou fusionnée avec la balise <head> existante. Pour cette raison, vous ne voulez généralement inclure qu’une seule balise <head> dans une page. Nous recommandons d’écrire cet unique <head> et son contenu dans un composant de mise en page.

Un `<style>` inattendu est inclus

Vous remarquerez peut-être que la balise <style> d’un composant importé est incluse dans votre source HTML même si ce composant n’apparaît pas dans la sortie finale. Par exemple, cela se produira avec les composants rendus conditionnellement qui ne sont pas affichés.

Le processus de Build d’Astro fonctionne sur le graphe des modules : une fois qu’un composant est inclus dans le modèle, sa balise <style> est traitée, optimisée et regroupée, qu’elle apparaisse ou non dans la sortie finale.

Échapper les caractères spéciaux dans Markdown

Certains caractères ont une signification particulière dans Markdown. Vous devrez peut-être utiliser une syntaxe différente si vous souhaitez les afficher. Pour ce faire, vous pouvez utiliser des entités HTML pour ces caractères.

Par exemple, pour éviter que < soit interprété comme le début d’un élément HTML, écrivez <.

Créer des reproductions minimales

Lorsque vous dépannez votre code, il peut être utile de créer une reproduction minimale du problème que vous pouvez partager. Il s’agit d’un projet Astro plus petit et simplifié qui démontre votre problème. Le fait d’avoir une reproduction fonctionnelle dans un nouveau projet permet de confirmer qu’il s’agit d’un problème reproductible et qu’il n’est pas dû à quelque chose d’autre dans votre environnement personnel ou dans un projet existant.

Le partage d’une reproduction minimale est utile lorsque vous demandez de l’aide dans nos fils d’assistance et est souvent nécessaire lorsque vous déposez un rapport de bogue auprès d’Astro.

Créer un StackBlitz via astro.new

Vous pouvez utiliser astro.new pour créer un nouveau projet Astro en un seul clic. Pour des reproductions minimales, nous recommandons fortement de partir de l’exemple minimal (vide) exécuté dans StackBlitz, avec le moins de code supplémentaire possible.

StackBlitz exécutera ce projet Astro dans le navigateur, en dehors de votre environnement local. Il vous fournira également un lien partageable afin que n’importe quel mainteneur Astro ou membre de l’équipe de support puisse voir votre reproduction minimale en dehors de leur propre environnement local. Cela signifie que tout le monde voit exactement le même projet, avec la même configuration et les mêmes dépendances. Il est ainsi plus facile pour quelqu’un d’autre d’aider à dépanner votre code. Si le problème est reproductible, cela vous permet de vérifier que le problème se trouve dans le code Astro lui-même et vous pouvez soumettre un rapport de bogue en toute confiance.

Notez que tous les problèmes ne sont pas reproductibles dans StackBlitz. Par exemple, votre problème peut dépendre d’un environnement spécifique ou d’un gestionnaire de packages, ou il peut impliquer le streaming HTML, qui n’est pas supporté par StackBlitz. Dans ce cas, créez un nouveau projet Astro minimal (vide) en utilisant le CLI, reproduisez le problème et téléchargez-le sur un dépôt GitHub. Au lieu de partager une URL StackBlitz, fournissez un lien vers le dépôt GitHub de votre reproduction minimale.

Code minimal

Une fois que votre projet vide est mis en place, passez par les étapes pour reproduire le problème. Cela peut inclure l’ajout de packages, la modification de la configuration et l’écriture de code.

Vous ne devez ajouter que le minimum de code nécessaire pour reproduire le problème. Ne reproduisez pas d’autres éléments de votre projet existant et supprimez tout le code qui n’est pas directement lié au problème.

Créer une Issue

Si votre problème peut être reproduit, il est temps de créer une issue et de déposer un rapport de bug !

Allez sur le dépôt Astro approprié sur GitHub et ouvrez une nouvelle issue. La plupart des dépôts ont un template d’issue qui pose des questions ou demande des informations pour le soumettre. Il est important que vous suiviez ces templates car si vous ne fournissez pas les informations dont nous avons besoin, nous devrons vous les demander… et personne ne travaillera sur votre problème !

Incluez le lien vers votre reproduction minimale sur StackBlitz (ou le dépôt GitHub, si nécessaire). Commencez par une description du comportement attendu par rapport au comportement réel pour fournir le contexte du problème. Ensuite, incluez des instructions claires, étape par étape, sur la façon de reproduire le problème dans un projet Astro.

Besoin de plus ?

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 s’il y a des propositions en rapport avec votre utilisation.

Contribuer

Communauté

Dépannage

Trucs et astuces

Débogage avec `console.log()`

Débogage des composants de Framework

Le composant `<Debug />` d’Astro

Erreurs courantes

Cannot use import statement outside a module

`document` (or `window`) is not defined

Expected a default export

Refused to execute inline script

Problèmes courants

Mon composant ne s’affiche pas

Mon composant n’est pas interactif

Cannot find package ‘X’

Utilisation d’Astro avec Yarn 2+ (Berry)

Ajouter des dépendances à Astro dans une monorepo

Utilisation de `<head>` dans un composant

Un `<style>` inattendu est inclus

Échapper les caractères spéciaux dans Markdown

Créer des reproductions minimales

Créer un StackBlitz via astro.new

Code minimal

Créer une Issue

Besoin de plus ?

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Envoyez-nous un commentaire

Envoyez-nous un commentaire

Dépannage

Trucs et astuces

Débogage avec console.log()

Débogage des composants de Framework

Le composant <Debug /> d’Astro

Erreurs courantes

Cannot use import statement outside a module

document (or window) is not defined

Expected a default export

Refused to execute inline script

Problèmes courants

Mon composant ne s’affiche pas

Mon composant n’est pas interactif

Cannot find package ‘X’

Utilisation d’Astro avec Yarn 2+ (Berry)

Ajouter des dépendances à Astro dans une monorepo

Utilisation de <head> dans un composant

Un <style> inattendu est inclus

Échapper les caractères spéciaux dans Markdown

Créer des reproductions minimales

Créer un StackBlitz via astro.new

Code minimal

Créer une Issue

Besoin de plus ?

Débogage avec `console.log()`

Le composant `<Debug />` d’Astro

`document` (or `window`) is not defined

Utilisation de `<head>` dans un composant

Un `<style>` inattendu est inclus