Installer Astro : prérequis, structure, premières commandes
Guide pas à pas pour créer un projet Astro fiable : Node.js, create-astro, arborescence src/, dev server et build de production sans mauvaise surprise.
Un démarrage propre évite des semaines de dette
Installer Astro prend quelques minutes. Poser une base saine — versions Node, structure de dossiers, scripts npm — évite des écarts entre le poste du développeur, la CI et la production. Ce guide suit la documentation officielle sur Install and setup en l'enrichissant des points de vigilance terrain.
Si vous découvrez le framework, lisez d'abord pourquoi l'architecture en îlots d'Astro change la donne côté performance.
Prérequis
- Node.js 18.20.8+ ou 20.3+ (vérifiez avec
node -v) ; - un gestionnaire de paquets : npm, pnpm ou yarn ;
- un éditeur avec support TypeScript recommandé.
Sur Linux ou macOS, privilégiez nvm ou fnm pour isoler la version Node par projet. Sur Windows, le installateur LTS depuis nodejs.org convient pour débuter.
Créer le projet
Lancez l'assistant officiel :
npm create astro@latest
Répondez aux questions :
- Template : « Empty » ou « Blog » selon votre objectif ;
- TypeScript : « strict » si vous visez la robustesse ;
- Install dependencies : oui pour gagner du temps.
Déplacez-vous dans le dossier généré :
cd mon-projet-astro
Arborescence à connaître
mon-projet-astro/
├── public/ # Assets servis tels quels (favicon, robots.txt)
├── src/
│ ├── components/ # Composants .astro et îles UI
│ ├── layouts/ # Gabarits de page
│ ├── pages/ # Routes (file-based routing)
│ └── styles/ # CSS global ou modules
├── astro.config.mjs # Configuration centrale
├── package.json
└── tsconfig.json
Le dossier src/pages/ pilote le routage : index.astro → /, about.astro → /about, blog/[slug].astro → routes dynamiques.
Lancer le serveur de développement
npm run dev
Par défaut, Astro écoute sur http://localhost:4321. Le rechargement à chaud (HMR) met à jour les composants sans redémarrage complet.
Si le port est occupé, Astro propose automatiquement le suivant. Notez l'URL affichée dans le terminal.
Première page
Créez src/pages/index.astro (ou modifiez le fichier généré) :
---
const titre = "Bienvenue sur Astro";
---
<html lang="fr">
<head>
<meta charset="utf-8" />
<title>{titre}</title>
</head>
<body>
<h1>{titre}</h1>
<p>Premier rendu statique, prêt pour le SEO.</p>
</body>
</html>
Le frontmatter entre --- s'exécute côté serveur au build ou à la requête : idéal pour charger des données sans les exposer au client.
Build et preview production
npm run build
npm run preview
build génère le dossier dist/ (par défaut). preview sert ce build localement pour détecter les erreurs absentes en dev (chemins d'assets, variables d'environnement, adaptateur manquant).
Ajoutez npm run astro check si TypeScript est activé : il remonte les erreurs de typage avant la CI.
Configuration minimale utile
Dans astro.config.mjs, définissez tôt l'URL de production :
import { defineConfig } from "astro/config";
export default defineConfig({
site: "https://mondomaine.fr",
});
Cette valeur alimente les URLs canoniques, le sitemap et les métadonnées Open Graph. Pour aller plus loin sur les intégrations et adaptateurs, voir maîtriser la configuration d'Astro.
Erreurs fréquentes au démarrage
- Version Node trop ancienne : erreurs cryptiques sur les modules ESM ;
- Mélange default/named export dans les intégrations ;
- Assets en dehors de
public/référencés avec un chemin absolu incorrect ; - Oubli de
siteen production : URLs relatives cassées dans le RSS ou le SEO.
Prochaines étapes
- Ajouter une intégration UI (React, Vue) uniquement si nécessaire.
- Structurer le contenu via content collections pour un blog ou une doc.
- Choisir un hébergeur compatible static ou SSR — quand choisir Astro pour un site statique.
- Configurer ESLint et la CI (build +
astro check).
Conclusion
L'installation Astro est simple ; la qualité du projet dépend des choix immédiats suivants : Node figé, site renseigné, scripts de build documentés. Avec cette base, vous exploitez le framework sur ce qu'il fait de mieux — livrer du HTML rapide et ajouter l'interactivité avec parcimonie.
Documentation : Getting started Astro.
Découvrez également
Cloudflare acquiert Astro : virage stratégique du web
L'acquisition d'Astro par Cloudflare accélère la convergence entre infrastructure edge et frameworks statiques orientés performance pour le web moderne.
Comparatif 2026 des meilleurs frameworks web
Comparatif 2026 des frameworks web : Next.js, Astro, Nuxt, SvelteKit et Angular, avec critères concrets pour choisir selon votre produit et votre équipe.
Astro et sites statiques : quand choisir cette voie
Quand privilégier Astro pour un site statique : cas d'usage concrets, limites honnêtes et critères de choix face à Next.js, Hugo ou un CMS headless.
Un projet web ou un audit SEO technique ?
Site vitrine, refonte ou amélioration des performances : je peux vous aider à clarifier la priorité, estimer le chantier et avancer sereinement.
Flux RSS
Suivre le blog sans e-mail
Copiez l'URL du flux et ajoutez-la dans Feedly, Feeder ou toute autre application RSS.
Web, mobile ou bureau : le principe reste le même.
Cette adresse fonctionne dans tout lecteur RSS : agrégateur web, application mobile ou logiciel de bureau.
Comment ajouter le flux
- Copiez l'URL du flux ci-dessus.
- Ouvrez votre lecteur RSS (Feedly, Feeder, NetNewsWire, etc.).
- Cherchez « Ajouter un flux », « Subscribe » ou le bouton +.
- Collez l'URL, validez : les prochains articles apparaîtront automatiquement.
Ajout rapide sur le web
Applications mobiles
Sur smartphone ou tablette, le principe reste le même : copiez l'URL, puis collez-la dans l'application.