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.

Prérequis

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

Compatibilité avec les navigateurs

Astro est construit avec Vite, qui cible par défaut les navigateurs supportant le JavaScript moderne. Pour une référence complète, vous pouvez consulter la liste des versions de navigateurs actuellement prises en charge par Vite.

Commencer un nouveau projet

Installer à partir de l’assistant CLI

Exécutez la commande suivante dans votre terminal pour commencer notre assistant d’installation pratique :
- npm
- pnpm
- yarn
Fenêtre de terminal
# créer un nouveau projet avec npm npm create astro@latest
Fenêtre de terminal
# créer un nouveau projet avec pnpm pnpm create astro@latest
Fenêtre de terminal
# créer un nouveau projet avec yarn yarn create astro
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.
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.
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

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.

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.

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 :

# 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>

# créer un nouveau projet avec un exemple officiel
pnpm create astro@latest --template <exemple-nom>

# créer un nouveau projet basé sur la branche main d'un dépôt GitHub
pnpm create astro@latest --template <utilisateur-github>/<depot-github>

# créer un nouveau projet avec un exemple officiel
yarn create astro --template <exemple-nom>

# créer un nouveau projet basé sur la branche main d'un dépôt GitHub
yarn create astro --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>.

Répondez aux questions et suivez les instructions de l’assistant CLI.
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 !

Éditer votre projet

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

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.

npm run dev

pnpm run dev

yarn 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 !

Travailler en mode développement

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

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

Configuration de l'éditeur Personnaliser votre éditeur de code pour améliorer l'expérience de développement avec Astro et débloquez de nouvelles fonctionnalités.

Barre d'outils de développement Explorez les fonctionnalités utiles de la barre d'outils de développement.

TypeScript avec Astro

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.

Créer et prévisualiser votre site

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 :

npm run build

pnpm build

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

Déployer votre nouveau site

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.

Prochaines étapes

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.

Explorer les fonctionnalités d’Astro

Comprendre votre base de code Apprenez-en plus sur la structure des fichiers Astro dans notre guide sur la structure de projet.

Créer des collections de contenu Ajoutez du contenu à votre nouveau site avec une validation du frontmatter et une sécurité de type automatique.

Ajouter des transitions de vue Créez des transitions de page et des animations fluides.

Apprenez-en davantage sur les îles En savoir plus sur l'architecture en îles d'Astro.

Suivre le tutorial d’introduction

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.

Configuration manuelle

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.

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.
- npm
- pnpm
- yarn
Fenêtre de terminal
npm init --yes
Fenêtre de terminal
pnpm init
Fenêtre de terminal
yarn init --yes
Installer Astro

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

Astro doit être installé localement, et non globalement. Assurez-vous que vous n’utilisez pas npm install -g astro pnpm add -g astro ou yarn add global astro.
- npm
- pnpm
- yarn
Fenêtre de terminal
npm install astro
Fenêtre de terminal
pnpm add astro
Fenêtre de terminal
yarn add 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.

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 :

---
// 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>

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: /
```
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.
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"
}
```
Consultez le guide d’Astro sur la configuration de TypeScript pour plus d’informations.
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
- astro.config.mjs
- package-lock.json ou yarn.lock, pnpm-lock.yaml, etc.
- package.json
- tsconfig.json
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 !

Contribuer

Communauté