Installation et Configuration d'Astro

Bienvenue dans cette première leçon fondamentale de notre cours "Maîtrisez Astro : Créez des Sites Web Ultra-Performants et SEO-Friendly avec l'Architecture en Îles". Aujourd'hui, nous allons jeter les bases de notre parcours en apprenant à installer et à configurer Astro sur votre machine. Une installation correcte et une compréhension de la configuration initiale sont cruciales pour exploiter pleinement la puissance d'Astro et construire des sites web exceptionnels.

Introduction à l'Installation d'Astro

Astro est un framework web moderne conçu pour construire des sites web rapides et optimisés pour le SEO, en adoptant une approche unique appelée "Architecture en Îles" (Islands Architecture). Contrairement à de nombreux frameworks JavaScript qui envoient une grande quantité de JavaScript au navigateur par défaut, Astro vise à livrer le moins de JavaScript possible, ce qui se traduit par des performances de chargement inégalées.

L'installation d'Astro est un processus simple et rapide, conçu pour vous permettre de démarrer un nouveau projet en quelques minutes. La configuration initiale, quant à elle, bien que souvent facultative pour les projets simples, devient essentielle pour personnaliser votre expérience de développement, intégrer des frameworks d'interface utilisateur (UI) comme React, Vue ou Svelte, et optimiser votre processus de build.

Dans cette leçon, vous apprendrez :

Les prérequis nécessaires pour installer Astro.
La procédure étape par étape pour créer un nouveau projet Astro.
La structure de base d'un projet Astro.
Comment configurer Astro via le fichier astro.config.mjs.
Comment ajouter et configurer des intégrations pour étendre les fonctionnalités d'Astro.

Prérequis

Avant de plonger dans l'installation d'Astro, assurez-vous d'avoir les outils suivants installés sur votre système :

Node.js (version 16.x ou supérieure) : Astro s'exécute sur Node.js. Vous pouvez le télécharger depuis le site officiel nodejs.org. Il est recommandé d'utiliser la version LTS (Long Term Support).
Un gestionnaire de paquets JavaScript :
- npm (Node Package Manager) : Généralement installé avec Node.js.
- Yarn (Yet Another Resource Negotiator) : Une alternative à npm. Vous pouvez l'installer via npm install -g yarn.
- pnpm (Performant Node Package Manager) : Une alternative plus récente et souvent plus rapide. Vous pouvez l'installer via npm install -g pnpm.
Nous utiliserons npm dans nos exemples, mais les commandes sont très similaires pour Yarn ou pnpm.
Un éditeur de code : Visual Studio Code (VS Code) est fortement recommandé en raison de son excellente intégration avec l'écosystème JavaScript/TypeScript et ses extensions Astro.
Connaissances de base du terminal/ligne de commande : Pour exécuter les commandes d'installation et de développement.

Installation d'Astro : Création d'un Nouveau Projet

Astro fournit une interface de ligne de commande (CLI) conviviale pour initialiser de nouveaux projets. La commande principale est npm create astro@latest.

Suivez ces étapes pour créer votre premier projet Astro :

Étape 1 : Ouvrez votre Terminal

Ouvrez votre terminal ou votre invite de commande (par exemple, PowerShell sur Windows, Terminal sur macOS/Linux).

Étape 2 : Exécutez la commande d'initialisation

Naviguez vers le répertoire où vous souhaitez créer votre projet, puis exécutez la commande suivante :

npm create astro@latest

Cette commande lancera un assistant interactif qui vous guidera à travers les choix de configuration initiaux.

Étape 3 : Suivez l'assistant interactif

L'assistant vous posera quelques questions :

Where should we create your new project? (Où devrions-nous créer votre nouveau projet ?)
- Entrez le nom de votre dossier de projet (par exemple, mon-site-astro). Astro créera un nouveau dossier avec ce nom.
How would you like to start your new project? (Comment souhaitez-vous démarrer votre nouveau projet ?)
- Use a few common samples (recommended) (Utiliser quelques exemples courants (recommandé)) : Crée un projet avec une page d'exemple, une page de blog, etc. Idéal pour commencer.
- Empty (Vide) : Crée un projet minimal sans contenu ni exemples.
- Blog : Crée un projet de blog complet avec des posts de blog, une page d'accueil, etc.
- Docs : Crée un projet de documentation.
- Portfolio : Crée un projet de portfolio.
- Landing Page : Crée une page d'atterrissage.
Pour cette leçon, nous choisirons Use a few common samples pour avoir un peu de contenu à explorer.
Install dependencies? (Installer les dépendances ?)
- Tapez y et appuyez sur Entrée. Astro utilisera votre gestionnaire de paquets préféré (npm, yarn ou pnpm) pour installer toutes les dépendances nécessaires.
Initialize a new git repository? (Initialiser un nouveau dépôt Git ?)
- Tapez y et appuyez sur Entrée (recommandé pour le contrôle de version).
How would you like to setup TypeScript? (Comment souhaitez-vous configurer TypeScript ?)
- Strict (Strict) : Configuration TypeScript la plus rigoureuse.
- Strictest (La plus stricte) : Encore plus stricte.
- Relaxed (Relaxée) : Configuration moins stricte, idéale pour commencer si vous n'êtes pas familier avec TypeScript.
- No (write JavaScript) (Non (écrire en JavaScript)) : N'active pas TypeScript.
Pour l'instant, Relaxed est un bon point de départ. Vous pouvez toujours ajuster cela plus tard.

L'assistant terminera en vous donnant des instructions sur la façon de démarrer votre serveur de développement.

# Exemple de sortie de la commande d'initialisation

# npm create astro@latest

# astro   greatest hits 🚀

# Where should we create your new project?
# › mon-site-astro
# How would you like to start your new project?
# › Use a few common samples (recommended)
# Install dependencies?
# › Yes
# Initialize a new git repository?
# › Yes
# How would you like to setup TypeScript?
# › Relaxed

# ✔ Project created!
#   Next steps:
#     cd mon-site-astro
#     npm run dev

#       ❤ Astro loves you.

Étape 4 : Naviguez dans votre répertoire de projet et démarrez le serveur de développement

cd mon-site-astro
npm run dev

Une fois que vous exécutez npm run dev, Astro démarrera un serveur de développement local. Vous verrez un message similaire à celui-ci dans votre terminal :

# Exemple de sortie de npm run dev

# > mon-site-astro@0.0.1 dev
# > astro dev

#   🚀 astro  v4.x.x ready in 150ms

#   ┃ Local    http://localhost:4321/
#   ┃ Network  use --host to expose
#   ┃ Pages    /
#   ┃          /blog
#   ┃          /markdown
#   ┃          /react
#   ┃          /svelte
#   ┃          /vue
#   ✔ Server started in 276ms

Ouvrez votre navigateur et naviguez vers l'adresse indiquée (généralement http://localhost:4321/). Vous devriez voir votre nouveau site Astro en action !

Félicitations ! Vous avez installé et démarré votre premier projet Astro.

Structure d'un Projet Astro

Comprendre la structure de base d'un projet Astro est essentiel pour savoir où placer vos fichiers et comment Astro les traite. Voici les répertoires et fichiers clés que vous trouverez dans un projet Astro par défaut :

mon-site-astro/
├── public/
│   └── favicon.svg
├── src/
│   ├── components/
│   │   └── Card.astro
│   ├── layouts/
│   │   └── Layout.astro
│   ├── pages/
│   │   ├── index.astro
│   │   └── blog.astro
│   └── env.d.ts
├── astro.config.mjs
├── package.json
├── tsconfig.json
└── README.md

public/ : Ce répertoire est destiné aux assets statiques qui ne nécessitent aucun traitement par Astro (images, polices, fichiers robots.txt, etc.). Les fichiers ici sont servis directement à la racine de votre site.
src/ : Le cœur de votre projet. C'est là que réside la majorité de votre code source.
- src/components/ : Contient vos composants Astro, ou des composants de frameworks UI (React, Vue, Svelte, etc.) que vous souhaitez réutiliser sur plusieurs pages.
- src/layouts/ : Contient vos mises en page (layouts) Astro, des composants .astro qui enveloppent d'autres contenus pour fournir une structure commune (en-tête, pied de page, navigation).
- src/pages/ : Contient les pages de votre site. Chaque fichier .astro (ou .md, .mdx, .ts, .js, etc.) dans ce répertoire devient un point de terminaison de votre site. Par exemple, src/pages/index.astro correspond à /, et src/pages/blog.astro à /blog. C'est le système de routage basé sur les fichiers d'Astro.
- src/env.d.ts : Fichier de déclaration de type pour TypeScript, souvent utilisé pour les variables d'environnement.
astro.config.mjs : Le fichier de configuration principal d'Astro (nous y reviendrons en détail ci-dessous).
package.json : Contient les métadonnées de votre projet et la liste de ses dépendances et scripts.
tsconfig.json : Le fichier de configuration TypeScript pour votre projet (si TypeScript est activé).
README.md : Un fichier Markdown décrivant votre projet.

Cette structure claire aide à organiser votre code et à maintenir la modularité, ce qui est particulièrement important avec l'Architecture en Îles d'Astro, où chaque composant peut être une "île" indépendante.

Configuration d'Astro avec `astro.config.mjs`

Le fichier astro.config.mjs est le centre de configuration de votre projet Astro. Il vous permet de personnaliser le comportement d'Astro, d'ajouter des intégrations, de définir des build options et bien plus encore.

Ce fichier est un module ES (d'où l'extension .mjs), ce qui signifie que vous utilisez la syntaxe import/export.

Structure de Base de `astro.config.mjs`

Voici à quoi ressemble un fichier astro.config.mjs typique :

// astro.config.mjs
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({
  // Vos options de configuration vont ici
});

La fonction defineConfig est une utilitaire d'Astro qui fournit une meilleure expérience développeur (complétion automatique, validation des types) lors de la configuration.

Options de Configuration Clés

Explorons les options de configuration les plus courantes et les plus importantes que vous trouverez ou que vous voudrez ajouter :

site : La base URL de votre site en production. Essentielle pour générer des sitemaps, des flux RSS et des URLs canoniques correctement.
```
export default defineConfig({
  site: 'https://www.mon-site-astro.com',
});
```

base : Un chemin de base si votre site est déployé dans un sous-répertoire (par exemple, https://example.com/mon-application-astro/).

export default defineConfig({
  base: '/mon-application-astro', // Le site sera accessible via http://localhost:4321/mon-application-astro/
});

integrations : L'une des options les plus puissantes d'Astro. Elle vous permet d'ajouter des plugins et des frameworks UI à votre projet. C'est ici que l'Architecture en Îles prend tout son sens. Vous pouvez avoir des îles React, Vue, Svelte, Lit, etc., coexistant sur la même page.
```
import { defineConfig } from 'astro/config';
import react from '@astrojs/react'; // Importez l'intégration React

export default defineConfig({
  integrations: [
    react(), // Active l'intégration React
    // d'autres intégrations comme vue(), svelte(), tailwind(), etc.
  ],
});
```
Nous aborderons l'ajout d'intégrations en détail dans la section suivante.
output : Définit le type de build d'Astro.
- 'static' (par défaut) : Génère un site statique (fichiers HTML, CSS, JS) qui peut être déployé sur n'importe quel hébergeur statique. Aucune exécution côté serveur.
- 'server' : Active le rendu côté serveur (SSR) ou les API endpoints. Nécessite un adaptateur (voir ci-dessous).
```
export default defineConfig({
  output: 'server', // Active le rendu côté serveur
});
```

adapter : Obligatoire si output est défini sur 'server'. Les adaptateurs permettent à Astro de s'exécuter dans différents environnements de serveur (Node.js, Vercel, Netlify, Deno, Cloudflare Pages, etc.).

import { defineConfig } from 'astro/config';
import node from '@astrojs/node'; // Pour Node.js SSR

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone' // Ou 'middleware'
  }),
});

markdown : Options spécifiques pour la compilation du Markdown. Vous pouvez configurer des plugins Remark (pour la transformation HTML) et Rehype (pour la transformation Markdown), des options de shorthand pour les composants, etc.

import { defineConfig } from 'astro/config';
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';

export default defineConfig({
  markdown: {
    // Active les composants Astro dans le Markdown (comme <MyComponent />)
    // et configure le balisage de ces composants.
    // astroFlavoredMarkdown: true, // Désactivé par défaut à partir d'Astro 4.x

    // Ajoute automatiquement des identifiants (IDs) aux titres pour les liens d'ancrage
    rehypePlugins: [rehypeSlug],
    // Génère une table des matières basée sur les titres Markdown
    remarkPlugins: [remarkToc],
  },
});

scopedStyleStrategy : Contrôle la façon dont Astro gère les styles scoped (définis dans des balises <style> sans attribut is:global).
- 'where' (par défaut) : Utilise des sélecteurs CSS where() pour un scoping léger.
- 'attribute' : Utilise des attributs de données (data-astro-cid-xxxx) pour un scoping plus strict.
```
export default defineConfig({
  scopedStyleStrategy: 'attribute',
});
```

Ces options constituent la base de la configuration de votre projet Astro. En les maîtrisant, vous pourrez adapter Astro à presque toutes les exigences de projet.

Ajout d'Intégrations (Exemple Pratique : React)

Les intégrations sont des plugins optionnels qui étendent les fonctionnalités d'Astro. Elles sont essentielles si vous souhaitez utiliser des frameworks UI comme React, Vue, Svelte, ou des outils comme Tailwind CSS, Mdx (Markdown étendu), etc.

Voyons comment ajouter l'intégration React à votre projet.

Étape 1 : Installer l'intégration React

Ouvrez votre terminal dans le répertoire de votre projet Astro et exécutez la commande d'installation :

npm install @astrojs/react

Étape 2 : Mettre à jour `astro.config.mjs`

Une fois l'intégration installée, vous devez l'ajouter à votre fichier astro.config.mjs.

Ouvrez astro.config.mjs et modifiez-le comme suit :

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react'; // 1. Importez l'intégration React

// https://astro.build/config
export default defineConfig({
  integrations: [
    react(), // 2. Ajoutez l'intégration à la liste
  ],
});

Explication :

Nous importons l'intégration react depuis le paquet @astrojs/react.
Nous l'ajoutons à l'array integrations en l'appelant comme une fonction (react()). Cela l'active pour votre projet.

Étape 3 : Créer et Utiliser un Composant React

Maintenant que React est configuré, vous pouvez créer un composant React et l'utiliser dans un fichier .astro.

Créez un nouveau fichier src/components/CompteurReact.jsx :

// src/components/CompteurReact.jsx
import React, { useState } from 'react';

function CompteurReact() {
  const [count, setCount] = useState(0);

  return (
    <div style={{ border: '1px solid gray', padding: '1rem', borderRadius: '8px' }}>
      <p>Ceci est un composant React.</p>
      <p>Le compteur est à : {count}</p>
      <button onClick={() => setCount(count + 1)}>Incrémenter</button>
      <button onClick={() => setCount(count - 1)} style={{ marginLeft: '0.5rem' }}>Décrémenter</button>
    </div>
  );
}

export default CompteurReact;

Maintenant, utilisez ce composant dans une page Astro, par exemple src/pages/index.astro :

---
import Layout from '../layouts/Layout.astro';
import CompteurReact from '../components/CompteurReact.jsx'; // Importez le composant React
---

<Layout title="Bienvenue sur Astro !">
  <main>
    <h1>Bienvenue sur Astro <span class="text-gradient">!</span></h1>
    <p class="instructions">
      Pour commencer, éditez <code>src/pages/index.astro</code> et enregistrez pour recharger.
    </p>

    <h2>Exemple de Composant React</h2>
    <!--
      Pour rendre un composant React interactif (une "île"),
      vous devez spécifier une directive client (e.g., client:load, client:visible).
      'client:load' le charge au démarrage de la page.
    -->
    <CompteurReact client:load />

    <p>
      Ce paragraphe est du HTML statique. Le composant ci-dessus est une "île" React
      qui s'hydrate indépendamment.
    </p>

    <!-- ... (reste de votre page index.astro) ... -->
  </main>
</Layout>

<style>
  /* ... (styles existants) ... */
</style>

Explication de client:load : C'est ici que l'Architecture en Îles d'Astro brille. Par défaut, Astro rend tous les composants en HTML statique. Pour qu'un composant de framework UI (comme notre CompteurReact) devienne interactif côté client (c'est-à-dire qu'il ait son JavaScript chargé et exécuté), vous devez lui ajouter une directive client:.

client:load : Charge et hydrate le composant JavaScript dès que la page est chargée.
client:idle : Charge et hydrate le composant une fois que le navigateur a terminé son rendu initial et est inactif.
client:visible : Charge et hydrate le composant lorsqu'il entre dans le viewport de l'utilisateur.
client:media="{query}" : Charge et hydrate le composant lorsque la requête média CSS spécifiée est satisfaite.
client:only="<framework>" : Ne rend le composant qu'au côté client, pas de pré-rendu HTML. Utile pour les composants qui dépendent fortement du navigateur ou qui ne peuvent pas être pré-rendus.

En utilisant ces directives, Astro ne charge et n'hydrate le JavaScript des composants que lorsque c'est absolument nécessaire, minimisant ainsi le JavaScript envoyé au navigateur et optimisant les performances.

Redémarrez votre serveur de développement (npm run dev) et visitez votre site. Vous devriez maintenant voir le composant React fonctionnel sur votre page d'accueil !

Workflow de Développement

Astro simplifie votre workflow de développement avec quelques commandes clés définies dans votre package.json :

npm run dev : Démarre le serveur de développement local. Il inclut le rechargement à chaud (Hot Module Replacement - HMR) pour une expérience de développement rapide. C'est la commande que vous utiliserez le plus souvent.
npm run build : Compile votre projet Astro pour la production. Cela génère les fichiers statiques (ou les fichiers serveur si vous utilisez SSR) dans le dossier dist/ (par défaut). Ces fichiers sont optimisés pour les performances.
npm run preview : Après avoir exécuté npm run build, cette commande vous permet de prévisualiser localement votre build de production. C'est utile pour vérifier que tout fonctionne comme prévu avant le déploiement.
npm run astro : La commande CLI directe d'Astro. Vous pouvez l'utiliser pour exécuter d'autres commandes Astro directement, comme npm run astro add <intégration>.

Conclusion

Dans cette leçon, vous avez appris à installer Astro, à comprendre la structure de base d'un projet, et à configurer ses aspects fondamentaux via astro.config.mjs. Nous avons également vu comment ajouter des intégrations, comme React, et comment utiliser les directives client: pour tirer parti de l'Architecture en Îles d'Astro.

Maîtriser ces étapes initiales est la clé pour construire des sites web performants et flexibles avec Astro. Vous êtes maintenant prêt à explorer la création de pages, de composants et à plonger plus profondément dans les concepts avancés d'Astro.

Points clés à retenir :

npm create astro@latest est votre point de départ.
Le répertoire src/pages gère le routage basé sur les fichiers.
astro.config.mjs est le fichier central pour toute configuration.
Les integrations étendent les fonctionnalités d'Astro et permettent l'usage de frameworks UI.
Les directives client: sont essentielles pour contrôler l'hydratation des "îles" JavaScript, garantissant des performances optimales.

Dans la prochaine leçon, nous explorerons la création de pages et de mises en page avec des composants Astro, et comment le système de fichiers influence le rendu de votre site.