Démarrer avec Astro

Astro s’est rapidement imposé comme l’un des générateurs de sites statiques les plus populaires, et pour de bonnes raisons. Son architecture en îlots rend le contenu statique en HTML tout en permettant aux fonctionnalités interactives d’activer le JavaScript côté client uniquement là où c’est nécessaire.

Ce guide parcourt les parties d’Astro que vous manipulerez pendant votre première semaine : mise en place du projet, composants, îlots, content collections, routage et déploiement. Il suppose que vous êtes à l’aise avec le HTML, un peu de TypeScript et la ligne de commande.

Créer votre premier projet

Démarrer avec Astro est simple. Ouvrez votre terminal et lancez la commande de création :

npm create astro@latest

L’assistant d’installation vous guide pour choisir un template, installer les dépendances et configurer TypeScript. Pour la plupart des projets, le template « Blog » constitue un excellent point de départ, avec des content collections déjà configurées.

Une fois l’installation terminée, lancez le serveur de développement :

cd my-site
npm run dev

Le site est servi sur http://localhost:4321 avec rechargement à chaud des modules. L’arborescence du projet est réduite et mérite d’être apprise tôt :

• src/pages/ contient les routes basées sur les fichiers. src/pages/about.astro devient /about.
• src/components/ contient les composants réutilisables. Astro ne traite pas ce dossier de façon particulière ; c’est une convention.
• src/layouts/ contient les gabarits de page, là encore par convention.
• public/ contient les fichiers copiés tels quels dans la sortie, comme favicon.svg ou robots.txt.
• astro.config.mjs contient les intégrations, les adaptateurs et les options de build.

Comprendre les composants Astro

Les composants Astro utilisent l’extension .astro et combinent une syntaxe proche du HTML avec une section de script en frontmatter. Contrairement aux composants React ou Vue, les composants Astro sont rendus en HTML statique au moment du build, sauf si vous activez explicitement l’hydratation côté client.

Le frontmatter du composant s’exécute sur le serveur au moment du build : vous avez accès aux imports de fichiers, à la récupération de données et aux fonctions utilitaires sans envoyer cette logique au navigateur.

---
interface Props {
  title: string;
  href?: string;
}

const { title, href = "/" } = Astro.props;
---

<article class="card">
  <h2><a href={href}>{title}</a></h2>
  <slot />
</article>

<style>
  .card {
    padding: 1.5rem;
    border-radius: 0.75rem;
  }
</style>

Quelques points de cet exemple méritent votre attention :

• Les props sont typées avec une simple interface Props. Les éditeurs et astro check la prennent en compte sans configuration supplémentaire.
• Les slots fonctionnent comme dans les web components. Un <slot /> par défaut reçoit les enfants, et les slots nommés (<slot name="footer" />) reçoivent les éléments marqués avec slot="footer".
• Les styles sont scopés par défaut. La règle .card ci-dessus ne s’applique qu’à ce composant. Utilisez <style is:global> lorsque vous avez réellement besoin d’une règle globale.

Si vous avez l’habitude de JSX, le principal ajustement est qu’il n’y a pas de re-rendu. Le template s’exécute une fois par requête ou par build, produit du HTML, et c’est terminé.

Îlots et directives client

Le HTML statique est la règle par défaut, mais vous aurez tôt ou tard besoin d’un élément interactif : un champ de recherche, un graphique, un panier. Astro vous permet d’intégrer des composants React, Preact, Svelte, Vue ou Solid après avoir ajouté l’intégration correspondante :

npx astro add react

Un composant de framework rendu sans directive ne produit toujours que du HTML. Pour envoyer son JavaScript et l’hydrater, ajoutez une directive client:* :

---
import Counter from "../components/Counter.tsx";
import Chart from "../components/Chart.tsx";
---

<Counter client:load />
<Chart client:visible />

Choisissez la directive selon l’urgence de l’interaction :

• client:load hydrate immédiatement. Utilisez-la pour les contrôles au-dessus de la ligne de flottaison dont l’utilisateur a besoin tout de suite.
• client:idle attend que le navigateur soit inactif. Idéal pour les widgets de moindre priorité.
• client:visible attend que le composant entre dans la zone visible. Parfait pour les graphiques et les contenus intégrés plus bas dans la page.
• client:media="(max-width: 768px)" n’hydrate que lorsqu’une media query correspond, par exemple pour un menu réservé au mobile.
• client:only="react" ignore complètement le rendu serveur, pour les composants qui dépendent des API du navigateur.

Chaque îlot s’hydrate indépendamment : un widget lent en bas de page ne bloque pas le reste. Pour de nombreuses interactions, vous n’avez même pas besoin d’un framework : une balise <script> dans un composant .astro est bundlée et dédupliquée par Astro, ce qui suffit souvent pour des bascules, des menus et des boutons de copie.

Les content collections

Les content collections font partie des fonctionnalités phares d’Astro. Elles offrent un accès typé à votre contenu Markdown et MDX, avec validation de schéma. Définissez une seule fois la structure de votre contenu, et Astro s’assurera que chaque élément respecte votre schéma.

Les collections sont définies dans src/content.config.ts. Depuis Astro 5, chaque collection utilise un loader qui indique à Astro d’où proviennent les entrées. Le loader intégré glob() lit les fichiers sur le disque :

import { defineCollection } from "astro:content";
import { glob } from "astro/loaders";
import { z } from "astro/zod";

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    publishDate: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

Si un article n’a pas de titre ou contient une date mal formée, le build échoue avec un message qui pointe vers le fichier. C’est exactement ce que vous voulez en équipe : les erreurs de contenu apparaissent en développement, pas en production.

Interroger une collection se fait en un seul appel de fonction, et les résultats sont entièrement typés :

---
import { getCollection } from "astro:content";

const posts = (await getCollection("blog", ({ data }) => !data.draft))
  .sort((a, b) => b.data.publishDate.valueOf() - a.data.publishDate.valueOf());
---

<ul>
  {posts.map((post) => (
    <li><a href={`/blog/${post.id}/`}>{post.data.title}</a></li>
  ))}
</ul>

Les loaders ne se limitent pas aux fichiers locaux. Le loader file() lit un unique fichier JSON ou YAML, et vous pouvez écrire votre propre loader pour récupérer des données depuis un CMS headless ou une API, tout en conservant la même validation de schéma et la même interface de requête.

Routage et pages dynamiques

Chaque fichier de src/pages/ est une route. Pour les pages générées à partir de données, comme une page par article de blog, utilisez un nom de fichier entre crochets et exportez getStaticPaths() :

---
// src/pages/blog/[id].astro
import { getCollection, render } from "astro:content";

export async function getStaticPaths() {
  const posts = await getCollection("blog");
  return posts.map((post) => ({ params: { id: post.id }, props: { post } }));
}

const { post } = Astro.props;
const { Content, headings } = await render(post);
---

<h1>{post.data.title}</h1>
<Content />

render() renvoie aussi les titres de l’article, ce qui est pratique pour construire une table des matières sans rien analyser vous-même.

Déploiement

Astro prend en charge plusieurs cibles de déploiement dès l’installation. Vercel, Netlify, Cloudflare Pages et les serveurs Node disposent chacun d’un adaptateur officiel que npx astro add installe et configure. Pour les sites statiques, la sortie par défaut ne demande aucune configuration supplémentaire.

La commande npm run build génère un site statique dans dist/, que n’importe quel hébergeur statique ou CDN peut servir. Lorsque vous avez besoin de code exécuté à chaque requête, par exemple pour le traitement de formulaires, l’authentification ou des pages personnalisées, ajoutez un adaptateur pour votre hébergeur :

npx astro add node

Avec un adaptateur installé, vous pouvez garder la plupart des pages prérendues et en exclure certaines routes avec export const prerender = false. Avant de déployer, définissez site dans astro.config.mjs pour que les URL canoniques, les sitemaps et les flux RSS pointent vers votre vrai domaine.

Pour aller plus loin

Une fois les bases bien assimilées, quelques fonctionnalités méritent d’être explorées, à peu près dans cet ordre :

1. Les images. Le composant <Image /> de astro:assets gère le redimensionnement, les formats modernes et les attributs de largeur et de hauteur qui évitent les décalages de mise en page.
2. Les view transitions. Ajouter le composant <ClientRouter /> à votre layout vous offre une navigation côté client animée avec très peu de code.
3. Les Actions. Les Astro Actions vous donnent des fonctions serveur typées avec validation des entrées, idéales pour les formulaires de contact et les inscriptions à une newsletter.
4. Les server islands. La directive server:defer permet à une page essentiellement statique de rendre à la demande un fragment personnalisé, comme un menu utilisateur.

Commencez petit : un layout, une collection, quelques pages. Astro récompense cette approche, car chaque page que vous ajoutez reste aussi rapide que la première.