Démarrez avec Astro Starlight

Mise à jour : 12/09/2024

Astro est un framework innovant qui se distingue par son approche centrée sur la performance, permettant de générer des pages statiques sans JavaScript côté client par défaut. Cela garantit des temps de chargement incroyablement rapides, une priorité essentielle dans le développement web actuel.

Starlight, quant à lui, est un thème spécialement conçu pour Astro, idéal pour les documentations techniques et les blogs. Avec Starlight, vous pouvez créer des pages claires, esthétiques et faciles à naviguer, tout en bénéficiant des performances accrues qu’offre Astro.

Dans ce guide, je vais vous accompagner pas à pas pour comprendre comment tirer parti de cet ensemble afin de créer des sites web performants et modernes.

Historique

Astro a été introduit en 2020 par l’équipe derrière Snowpack, un autre outil de construction web axé sur la rapidité et l’efficacité. L’objectif principal d’Astro était de réinventer la manière dont les sites web statiques sont construits, en se concentrant sur la performance et la simplicité. En supprimant par défaut le JavaScript côté client, Astro garantit des temps de chargement rapides et une meilleure expérience utilisateur, en particulier sur les connexions lentes ou les appareils moins puissants.

Au fil du temps, Astro a évolué pour inclure le support de multiples frameworks populaires tels que React, Vue et Svelte, tout en continuant à offrir des optimisations puissantes comme le rendu statique et l’intégration JavaScript progressive.

Starlight est né en réponse à un besoin croissant de thèmes optimisés pour la documentation technique et les blogs au sein de l’écosystème Astro. Développé spécifiquement pour tirer parti des capacités d’Astro, Starlight a été conçu pour offrir une mise en page propre, intuitive et facile à personnaliser. Il s’est rapidement imposé comme un choix de prédilection pour les développeurs souhaitant créer des sites de documentation qui allient esthétisme et performance.

Concepts clés d’Astro

Astro se distingue par plusieurs concepts fondamentaux qui définissent son approche unique dans la création de sites web statiques. Comprendre ces concepts est essentiel pour tirer le meilleur parti de ce framework.

Composants Astro

Les composants Astro sont au cœur de la construction d’une interface utilisateur dans Astro. Un composant Astro est un bloc réutilisable de code qui peut contenir du HTML, du CSS et même du JavaScript, mais l’élément clé est que seul le HTML est rendu par défaut. Cela permet de réduire considérablement la quantité de JavaScript envoyée au client, ce qui améliore les performances. Chaque composant est encapsulé, ce qui signifie qu’il ne peut pas interférer avec d’autres parties de l’application, assurant ainsi une meilleure modularité et maintenabilité du code.

Rendu statique par défaut

L’un des aspects les plus puissants d’Astro est son rendu statique par défaut. Contrairement à d’autres frameworks qui envoient souvent un mélange de HTML et de JavaScript au client, Astro génère uniquement du HTML statique lors de la compilation. Cela signifie que chaque page est complètement rendue côté serveur et n’a pas besoin de JavaScript pour s’afficher. Cela se traduit par des temps de chargement extrêmement rapides, car le navigateur n’a pas besoin de traiter et d’exécuter du JavaScript avant de pouvoir afficher la page.

Hydratation partielle

Astro introduit un concept innovant appelé hydratation partielle. Avec l’hydratation partielle, vous pouvez choisir d’ajouter du JavaScript seulement là où c’est nécessaire et uniquement lorsque l’utilisateur en a besoin. Par exemple, si un composant a besoin d’une interactivité complexe, vous pouvez spécifier qu’il doit être hydraté côté client, tandis que le reste de la page reste statique. Cela permet de maintenir une performance optimale tout en offrant une expérience utilisateur riche.

Intégration de multiples frameworks

Astro est conçu pour être flexible et interopérable avec les autres écosystèmes de développement web. Il prend en charge l’intégration de multiples frameworks tels que React, Vue, Svelte et Solid. Cela signifie que vous pouvez continuer à utiliser les bibliothèques de composants que vous connaissez déjà, tout en bénéficiant des optimisations offertes par Astro. Par exemple, vous pouvez avoir une page principalement composée de composants React, tout en utilisant des composants Svelte là où ils sont plus performants ou plus appropriés.

Système de routage simplifié

Le système de routage d’Astro est simple mais puissant. Il repose sur la structure des fichiers dans le répertoire src/pages. Chaque fichier dans ce répertoire correspond à une route dans l’application. Par exemple, un fichier about.astro dans ce répertoire générera une page accessible via /about. Cette approche permet de visualiser et de gérer facilement la structure des routes de votre site, sans avoir besoin de configuration supplémentaire.

Optimisation des performances

Astro inclut des outils d’optimisation des performances intégrés, tels que la réduction de la taille des fichiers, la compression et l’optimisation des images. Ces outils fonctionnent automatiquement pendant le processus de construction pour assurer que votre site est aussi léger et rapide que possible. De plus, Astro supporte le rendu côté serveur (SSR) et le pré-rendu (prerendering), ce qui vous permet de choisir la meilleure méthode pour chaque page, en fonction des besoins spécifiques de votre application.

Prise en charge des CSS et des préprocesseurs

Astro permet l’utilisation de CSS directement dans les composants et prend en charge les préprocesseurs CSS comme Sass ou Less. Vous pouvez ainsi styliser vos composants avec les outils et méthodes que vous préférez, tout en bénéficiant d’une isolation des styles par composant, évitant ainsi les conflits de styles globaux.

Prise en charge des plugins et des intégrations

Enfin, Astro est extensible grâce à un système de plugins et d’intégrations. Que vous ayez besoin de fonctionnalités supplémentaires comme l’internationalisation, la gestion des formulaires ou l’intégration d’API externes, il existe probablement un plugin ou une intégration pour cela. Vous pouvez également créer vos propres plugins si vous avez des besoins spécifiques.

Starlight

Starlight est un thème spécialement conçu pour Astro Build, destiné principalement aux créateurs de documentations techniques et de blogs. Il offre une solution prête à l’emploi qui combine une présentation claire, une navigation intuitive, et une personnalisation facile. Starlight est particulièrement adapté pour les projets où la lisibilité et l’organisation du contenu sont primordiales. En plus de ses fonctionnalités de base, Starlight intègre également des options avancées comme un moteur de recherche interne avec Pagefind, un thème sombre et clair, la prise en charge du multi-langue.

Installation d’Astro

L’installation d’Astro est simple et accessible, que vous soyez un développeur expérimenté ou un débutant. Ce chapitre va détailler les étapes pour configurer un nouveau projet Astro, ainsi que quelques configurations initiales pour bien démarrer.

a. Prérequis

Avant d’installer Astro, assurez-vous que vous avez les outils suivants installés sur votre système :

Node.js (version 20) : Astro est construit sur Node.js, donc une version récente est nécessaire pour exécuter les commandes et gérer les dépendances.
npm (ou Yarn) : Utilisé pour installer Astro et ses dépendances. npm est généralement inclus avec Node.js.

Créer un nouveau projet Astro

La façon la plus simple de démarrer avec Astro est d’utiliser l’outil create-astro, qui vous guide à travers le processus de création d’un nouveau projet. Pour cela, ouvrez votre terminal et exécutez la commande suivante :

npm create astro@latest -- --template starlight

Cette commande vous invite à sélectionner un modèle de projet parmi plusieurs options proposées (par exemple, un projet vide, un blog, une documentation, etc.). Vous pouvez choisir un modèle de base ou un modèle spécifique à un cas d’usage particulier.

> npx
> create-astro --template starlight


 astro   Launch sequence initiated.

   dir   Where should we create your new project?
         ./violet-visual
      ◼  tmpl Using starlight as project template

    ts   Do you plan to write TypeScript?
         Yes

   use   How strict should TypeScript be?
         Strict

  deps   Install dependencies?
         Yes

   git   Initialize a new git repository?
         Yes

      ✔  Project initialized!
         ■ Template copied
         ■ TypeScript customized
         ■ Dependencies installed
         ■ Git initialized

  next   Liftoff confirmed. Explore your project!

         Enter your project directory using cd ./violet-visual
         Run npm run dev to start the dev server. CTRL+C to stop.
         Add frameworks like react or tailwind using astro add.

         Stuck? Join us at https://astro.build/chat

╭─────╮  Houston:
│ ◠ ◡ ◠  Good luck out there, astronaut! 🚀
╰─────╯

Une fois que vous avez choisi votre modèle, vous devrez nommer votre projet et choisir si vous souhaitez utiliser TypeScript (une option recommandée pour les projets de plus grande envergure ou pour ceux qui veulent bénéficier de la sécurité des types).

Structure du projet

Une fois votre projet créé, vous trouverez une structure de répertoires similaire à la suivante :

Répertoiremon-projet-astro
- Répertoirepublic/
  - …
- Répertoiresrc
  - Répertoirecomponents/
    …
  - Répertoirelayouts/
    …
  - Répertoirepages/
    …
  - Répertoirestyles/
    …
- package.json
- astro.config.mjs

public/ : Contient les fichiers statiques qui seront directement accessibles via l’URL de votre site (par exemple, les images, les polices, etc.).
src/ : Contient le code source de votre site. Les pages, composants, et styles sont organisés dans des sous-répertoires :
- components/ : Répertoire pour vos composants Astro réutilisables.
- layouts/ : Contient les dispositions (layouts) que vous pouvez appliquer à vos pages pour unifier leur structure.
- pages/ : Chaque fichier .astro ou .md dans ce répertoire correspond à une route distincte de votre site.
- styles/ : Stocke les fichiers CSS ou les préprocesseurs CSS comme Sass.
- astro.config.mjs : Le fichier de configuration principal d’Astro, où vous pouvez ajuster les paramètres du projet et intégrer des plugins ou des fonctionnalités supplémentaires.

Configuration initiale

Vous pouvez configurer votre projet Astro en modifiant le fichier astro.config.mjs. Par exemple, vous pouvez modifier le dossier de sortie (où les fichiers générés seront placés) ou les liens vers vos comptes sociaux.

Voici un exemple de configuration de base :

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      social: {
        github: 'https://github.com/withastro/starlight',
      },
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
      ],
    }),
  ],
});

Démarrer le serveur de développement

Une fois les dépendances installées et votre structure de projet en place, vous pouvez lancer le serveur de développement pour voir votre site en action. Exécutez la commande suivante :

npm run dev
> site@0.0.1 dev
> astro dev

21:28:44 [types] Generated 1ms

 astro  v4.14.3 ready in 160 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

21:28:44 watching for file changes...
21:28:48 [200] / 6ms

Cette commande démarre un serveur local et ouvre votre site dans le navigateur à l’adresse http://localhost:4321. Le serveur de développement d’Astro prend en charge le rechargement à chaud, ce qui signifie que chaque modification que vous apportez à vos fichiers se reflète instantanément dans le navigateur.

site par défaut

Ajouter du contenu

Starlight est maintenant configuré et il est temps d’ajouter du contenu ! Ajouter un fichier test.md dans le dossier src/contentt/guides/reference :

---
title: Une page de documentation
description: En savoir plus sur mon projet dans ce site de documentation construit avec Starlight.
---
## Titre deux

Bienvenue dans mon projet !

Déploiement d’un site Astro sur un serveur web Nginx

Avant de déployer votre site sur un serveur Nginx par exmple, vous devez d’abord générer les fichiers statiques de votre projet Astro. Cela se fait en exécutant la commande de construction suivante dans votre terminal :

npm run build

Cette commande compile votre projet Astro et génère les fichiers HTML, CSS, et JavaScript nécessaires dans le répertoire dist/. Ce répertoire contient tout ce dont vous avez besoin pour déployer votre site.

Transfert des fichiers sur le serveur

Une fois les fichiers statiques générés, vous devez les transférer sur votre serveur. Vous pouvez utiliser des outils comme SCP (Secure Copy) ou rsync pour copier les fichiers du répertoire dist/ vers le répertoire de votre choix sur le serveur.

Voici un exemple de commande rsync pour transférer les fichiers :

rsync -avz dist/ user@your-server:/var/www/mon-site-astro

Dans cet exemple, remplacez user par votre nom d’utilisateur et your-server par l’adresse IP ou le nom de domaine de votre serveur. /var/www/mon-site-astro est le répertoire où les fichiers de votre site seront stockés.

Conclusion

Dans ce guide, nous avons exploré les bases d’Astro, en passant par son installation, la configuration initiale, et enfin, le déploiement de votre site sur un serveur Nginx. Ces étapes vous permettent de créer un site web moderne, performant, et bien sécurisé, prêt à être accessible par vos utilisateurs.

Cependant, il ne s’agit que du début de notre aventure avec Astro. Dans un second billet de blog qui sera publié dans les prochains jours, je vais approfondir certains aspects plus avancés.

Ressources de référence

Pour approfondir votre utilisation d’Astro Build et de Starlight, voici quelques ressources clés :

Site officiel d’Astro : Point de départ pour explorer les fonctionnalités d’Astro, avec des tutoriels et des exemples. https://astro.build/ ↗
Documentation d’Astro : Guide complet pour comprendre et maîtriser Astro. https://docs.astro.build/ ↗
Projet Starlight sur GitHub : Code source, issues, et mises à jour du thème Starlight. https://github.com/withastro/starlight ↗
Documentation de Starlight : Instructions pour personnaliser et utiliser Starlight, y compris Pagefind et les thèmes. https://starlight.docs.astro.build/ ↗