Aller au contenu

Installer et configurer Astro

La commande CLI create astro est le moyen le plus rapide pour démarrer un nouveau projet vierge Astro. Elle vous accompagnera à travers chaque étape pour configurer votre nouveau projet Astro et elle vous permettra de choisir parmi différents modèles de démarrage officiels.

Ou, vous pouvez démarrer votre projet en utilisant n’importe quel thème ou modèle de démarrage existant.

Si vous préférez installer Astro manuellement, consultez notre guide d’installation manuelle étape par étape.

  • Node.js - v18.17.1 ou v20.3.0 ou supérieure. ( v19 n’est pas supportée.)
  • Éditeur de texte - Nous recommandons VS Code avec notre extension officielle Astro.
  • Terminal - Astro est accessible via son interface en ligne de commande (CLI).

Installer à partir de l’assistant CLI

Titre de la section Installer à partir de l’assistant CLI
  1. Exécutez la commande suivante dans votre terminal pour commencer notre assistant d’installation pratique :

    Fenêtre de terminal
    # créer un nouveau projet avec npm
    npm create astro@latest

    Vous pouvez exécuter create astro n’importe où sur votre machine, ainsi vous n’avez pas besoin de créer un nouveau dossier vide pour votre projet avant de démarrer. Si vous n’avez pas encore de dossier vide pour votre nouveau projet, l’assistant vous aidera à en créer un automatiquement.

    Si tout se passe bien, vous verrez un message de réussite suivi par quelques étapes recommandées. Maintenant que votre projet a été créé, vous pouvez utiliser la commande cd pour vous déplacer dans le dossier de votre nouveau projet pour commencer à utiliser Astro.

  2. Si vous avez ignoré l’étape npm install proposée par l’assistant CLI, alors assurez-vous d’installer vos dépendances avant de continuer.

  3. Vous pouvez maintenant démarrer le serveur de développement d’Astro et visualiser un aperçu en direct de votre projet pendant que vous le construisez !

Utiliser un thème ou un modèle de démarrage

Titre de la section Utiliser un thème ou un modèle de démarrage

Vous pouvez également démarrer un nouveau projet Astro en vous basant sur un exemple officiel ou sur la branche main de n’importe quel dépôt Github en utilisant l’argument --template avec la commande create astro.

  1. Explorez notre vitrine de thèmes et de modèles de démarrage où vous trouverez des thèmes pour construire des blogs, des portfolios, des sites de documentation, des pages de destination, et plus encore ! Ou, recherchez sur GitHub pour trouver encore plus de projets de démarrage.

  2. Exécutez la commande suivante dans votre terminal, en remplaçant le nom du modèle de démarrage officiel d’Astro, ou les noms d’utilisateur et de dépôt GitHub du thème que vous souhaitez utiliser :

    Fenêtre de terminal
    # créer un nouveau projet avec un exemple officiel
    npm create astro@latest -- --template <exemple-nom>
    # créer un nouveau projet basé sur la branche main d'un dépôt GitHub
    npm create astro@latest -- --template <utilisateur-github>/<depot-github>

    Par défaut, cette commande utilisera la branche main du dépôt du modèle. Pour utiliser un nom de branche différent, renseignez-le au travers de l’argument --template : <utilisateur-github>/<depot-github>#<branche>.

  3. Répondez aux questions et suivez les instructions de l’assistant CLI.

  4. Vous pouvez maintenant démarrer le serveur de développement d’Astro et visualiser un aperçu en direct de votre projet pendant que vous vous l’appropriez !

Pour apporter des modifications à votre projet, ouvrez le dossier de votre projet dans votre éditeur de code. Travailler en mode développement avec le serveur de développement en cours d’exécution vous permet de voir les mises à jour sur votre site pendant que vous éditez votre code.

Vous pouvez aussi personnaliser les aspects de votre environnement de développement comme configurer Typescript ou installer les extensions officielles d’Astro pour votre éditeur.

Démarrer le serveur de développement d’Astro

Titre de la section Démarrer le serveur de développement d’Astro

Astro est livré avec un serveur de développement intégré qui possède tout ce dont vous avez besoin pour le développement de votre projet. La commande CLI astro dev démarrera le serveur de développement local pour que vous puissiez voir votre nouveau site web en action pour la toute première fois.

Chaque modèle de démarrage est livré avec un script pré-configuré qui exécutera astro dev pour vous. Après être entré dans le dossier de votre projet, utilisez votre gestionnaire de paquet préféré pour exécuter cette commande et démarrer le serveur de développement d’Astro.

Fenêtre de terminal
npm run dev

Si tout se passe bien, Astro va maintenant rendre votre projet disponible à l’adresse http://localhost:4321/. Visitez ce lien dans votre navigateur et consultez votre nouveau site !

Astro écoutera en direct les changements apportés aux fichiers dans votre dossier src/ et mettra à jour l’aperçu de votre site au fur et à mesure de sa construction. Ainsi vous n’aurez pas besoin de redémarrer le serveur lorsque vous faîtes des changements au cours du développement. Vous verrez toujours une version à jour de votre site dans votre navigateur quand le serveur de développement est en cours d’exécution.

Quand vous consultez votre site dans votre navigateur, vous aurez accès à la barre d’outils de développement d’Astro. Au fur et à mesure que vous construisez, il vous aidera à inspecter vos îles, à repérer les problèmes d’accessibilité, et plus encore.

Si vous n’êtes pas en mesure d’ouvrir votre projet dans un navigateur après avoir démarré le serveur de développement, retournez dans le terminal où vous avez exécuté la commande dev et vérifiez le message affiché. Il devrait vous informer si une erreur est survenue, ou si votre projet est accessible à une adresse différente de http://localhost:4321/.

Configurer votre environnement de développement

Titre de la section Configurer votre environnement de développement

Explorez les guides ci-dessous pour personnalier votre expérience de développement.

Astro est livré avec un support intégré pour TypeScript ce qui peut aider à éviter les erreurs au moment de l’exécution en définissant les formes des objets et composants dans votre code.

Vous n’avez pas besoin d’écrire du code Typescript dans vos projets Astro pour en bénéficier. Astro évalue toujours le code de votre composant comme étant du code Typescript, et l’extension VSCode Astro déduira autant que possible pour fournir l’auto-complétion, des astuces et des erreurs dans votre éditeur.

Apprenez-en plus sur l’utilisation et la configuration de TypeScript avec Astro.

Pour vérifier la version de votre site qui sera créé au moment de la génération, fermez le serveur (Ctrl + C) et exécutez la commande de construction appropriée pour votre gestionnaire de paquets dans votre terminal :

Fenêtre de terminal
npm run build

Astro construira une version prête à être déployée de votre site dans un dossier séparé (dist/ par défaut) et vous pourrez suivre sa progression dans le terminal. Cela vous alertera de toute erreur de construction dans votre projet avant de le déployer en production. Si TypeScript est configuré sur strict ou strictest, le script build vérifiera également votre projet pour les erreurs de type.

Une fois la construction terminée, exécutez la commande preview appropriée (par exemple npm run preview) dans votre terminal et vous pourrez afficher la version construite de votre site localement dans la même fenêtre d’aperçu du navigateur.

Notez que cela donne un aperçu de votre code tel qu’il existait lors de la dernière exécution de la commande de construction. Ceci est destiné à vous donner un aperçu de l’apparence de votre site une fois déployé sur le web. Toute modification ultérieure que vous apporterez à votre code après la construction ne sera pas reflétée lors de la prévisualisation de votre site jusqu’à ce que vous exécutiez à nouveau la commande de construction.

Utilisez (Ctrl + C) pour fermer l’aperçu et exécuter une autre commande de terminal, comme redémarrer le serveur de développement pour travailler à nouveau in development mode qui est capable de suivre les modifications apportées à votre code pour afficher un aperçu en direct de ces modifications.

Apprenez-en plus sur le CLI d’Astro et les commandes de terminal que vous utiliserez pour développer avec Astro.

Vous souhaiterez peut-être déployer votre nouveau site immédiatement avant de commencer à ajouter ou modifier trop de code. Ceci est utile pour publier une version minimale et fonctionnelle de votre site et peut vous faire gagner du temps et des efforts supplémentaires pour dépanner votre déploiement ultérieurement.

Victoire ! Vous êtes maintenant prêt à commencer à construire avec Astro ! 🥳

Voici quelques éléments que nous vous recommandons d’explorer ensuite. Vous pouvez les lire dans n’importe quel ordre. Vous pouvez même quitter un peu notre documentation et aller jouer dans la base de code de votre nouveau projet Astro, en revenant ici chaque fois que vous rencontrez des problèmes ou avez une question.

Construire un blog Astro entièrement fonctionnel en commençant avec une seule page vierge dans notre tutoriel d’introduction.

C’est un excellent moyen de voir comment Astro fonctionne et vous guide à travers les bases des pages, des mises en page, des composants, du routage, des îles et bien plus encore. Il comprend également une unité facultative adaptée aux débutants pour les nouveaux venus dans les concepts de développement web en général, qui vous guidera dans l’installation des applications nécessaires sur votre ordinateur, la création d’un compte GitHub et le déploiement de votre site.

Ce guide vous accompagnera à travers les étapes pour installer et configurer manuellement un nouveau projet Astro.

Si vous préférez ne pas utiliser notre outil CLI automatique create astro, vous pouvez configurer votre projet par vous-même en suivant le guide ci-dessous.

  1. Créez votre dossier

    Créez un dossier vide portant le nom de votre projet, puis entrez à l’intérieur.

    Fenêtre de terminal
    mkdir mon-projet-astro
    cd mon-projet-astro

    Une fois que vous êtes dans votre nouveau répertoire, créez le fichier package.json de votre projet. C’est ainsi que vous gérerez les dépendances de votre projet, y compris Astro. Si vous n’êtes pas familier avec ce format de fichier, exécutez la commande suivante pour en créer un.

    Fenêtre de terminal
    npm init --yes
  2. Installer Astro

    Commencez par installer les dépendances du projet Astro dans votre projet.

    Fenêtre de terminal
    npm install astro

    Puis, remplacez toute section réservée « scripts » de votre package.json par ce qui suit :

    package.json
    "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
    },

    Vous utiliserez ces scripts plus loin dans le guide pour démarrer Astro et exécuter ses différentes commandes.

  3. Créez votre première page

    Dans votre éditeur de texte, créez un nouveau fichier dans votre dossier à l’emplacement src/pages/index.astro. Ce sera votre première page Astro dans le projet.

    Pour ce guide, copiez et collez l’extrait de code suivant (en incluant les tirets ---) dans votre nouveau fichier :

    src/pages/index.astro
    ---
    // Bienvenue dans Astro ! Tout ce qui se trouve entre ces barrières de code
    // à trois tirets est le « frontmatter de votre composant ». Il ne s'exécute
    // jamais dans le navigateur.
    console.log("Ceci s'exécute dans votre terminal, et non dans le navigateur !");
    ---
    <!-- Ci-dessous se trouve le « modèle de votre composant ». C'est simplement
    du HTML, mais avec un peu de magie à l'intérieur pour vous aider à
    construire de superbes modèles. -->
    <html>
    <body>
    <h1>Hello, World!</h1>
    </body>
    </html>
    <style>
    h1 {
    color: orange;
    }
    </style>
  4. Créez votre première ressource statique

    Vous voudrez également créer un dossier public/ pour stocker vos ressources statiques. Astro inclura toujours ces ressources dans votre version finale, afin que vous puissiez les référencer en toute sécurité à partir de vos modèles de composants.

    Dans votre éditeur de texte, créez un nouveau fichier dans votre dossier à l’emplacement public/robots.txt. robots.txt est un fichier simple que la plupart des sites incluent pour indiquer aux robots de recherche comme Google comment traiter votre site.

    Pour ce guide, copiez et collez l’extrait de code suivant dans votre nouveau fichier :

    public/robots.txt
    # Exemple : Autoriser tous les robots à scanner et indexer votre site.
    # Syntaxe complète : https://developers.google.com/search/docs/advanced/robots/create-robots-txt
    User-agent: *
    Allow: /
  5. Créez astro.config.mjs

    Astro est configuré en utilisant astro.config.mjs. Ce fichier est optionnel si vous n’avez pas besoin de configurer Astro mais vous souhaiterez peut-être le créer maintenant.

    Créez astro.config.mjs à la racine de votre projet et copiez le code ci-dessous à l’intérieur :

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    // https://astro.build/config
    export default defineConfig({});

    Si vous souhaitez ajouter des composants de framework UI comme React, Svelte, etc. ou utiliser d’autres outils comme Tailwind ou Partytown dans votre projet, c’est ici que vous importerez et configurerez manuellement les intégrations.

    Consultez la référence de configuration de l’API d’Astro pour plus d’informations.

  6. Ajoutez le support de TypeScript

    TypeScript est configuré en utilisant tsconfig.json. Même si vous n’écrivez pas de code TypeScript, ce fichier est important pour que les outils comme Astro et VS Code puisse comprendre votre projet. Certaines fonctionnalités (comme l’import de paquets npm) ne sont pas entièrement supportés dans l’éditeur sans un fichier tsconfig.json.

    Si vous avez l’intention d’écrire du code Typescript, l’utilisation des modèles strict ou strictest d’Astro est recommandé. Vous pouvez consulter et comparer les trois modèles de configuration dans astro/tsconfigs/.

    Créez tsconfig.json à la racine de votre projet et copiez le code ci-dessous à l’intérieur. (Vous pouvez utiliser base, strict ou strictest pour votre modèle TypeScript) :

    tsconfig.json
    {
    "extends": "astro/tsconfigs/base"
    }

    Finalement, créez src/env.d.ts pour informer TypeScript des types ambiants disponibles dans un projet Astro :

    src/env.d.ts
    /// <reference types="astro/client" />

    Consultez le guide d’Astro sur la configuration de TypeScript pour plus d’informations.

  7. Prochaines étapes

    Si vous avez suivi les étapes ci-dessus, le dossier de votre projet devrait maintenant ressembler à ça :

    • Répertoirenode_modules/
    • Répertoirepublic/
      • robots.txt
    • Répertoiresrc/
      • Répertoirepages/
        • index.astro
      • env.d.ts
    • astro.config.mjs
    • package-lock.json ou yarn.lock, pnpm-lock.yaml, etc.
    • package.json
    • tsconfig.json
  8. Vous pouvez maintenant démarrer le serveur de développement d’Astro et visualiser un aperçu en direct de votre projet pendant que vous le construisez !