Astro : installation et structure

Astro est un framework web orienté contenu : il produit par défaut du HTML statique sans JavaScript côté client, et n’ajoute du JavaScript que pour les composants interactifs (« îlots »). Cette rubrique décrit Astro 7. Les exemples utilisent des noms génériques (monsite).

Prérequis

Node.js récent (voir Node.js : installation) : Astro exige une version LTS actuelle ; la version exacte se lit dans le champ engines du paquet astro (npm view astro engines).

node --version
npm --version

Créer un projet

npm create astro@latest monsite
cd monsite
npm run dev

L’assistant propose un modèle (minimal, blog, documentation), TypeScript (strict recommandé), l’installation des dépendances et l’initialisation de Git. Avec pnpm : pnpm create astro@latest (voir Node.js : pnpm et Yarn).

Le serveur de développement écoute sur http://localhost:4321 ; pour y accéder depuis un autre poste (serveur distant) :

npm run dev -- --host 127.0.0.1
ssh -N -L 4321:127.0.0.1:4321 utilisateur@serveur.exemple.com

puis ouvrir http://localhost:4321 sur le poste local (voir SSH : tunnels). Éviter --host 0.0.0.0 sur un serveur exposé.

Structure

monsite/
├── astro.config.mjs        # configuration
├── package.json
├── tsconfig.json
├── public/                 # fichiers servis tels quels (robots.txt, favicon, images)
└── src/
    ├── pages/              # une page = une route
    ├── layouts/            # gabarits de page
    ├── components/         # composants réutilisables
    ├── content/            # contenu Markdown (collections)
    ├── content.config.ts   # schémas des collections
    └── styles/             # feuilles de style globales

Dossier	Rôle
`src/pages/`	Obligatoire : chaque fichier devient une URL
`public/`	Copié sans traitement à la racine du site
`src/` (le reste)	Traité à la compilation (optimisation, regroupement)

Commandes

Commande	Effet
`npm run dev`	Serveur de développement avec rechargement
`npm run build`	Site de production dans `dist/`
`npm run preview`	Sert `dist/` localement pour contrôle
`npx astro check`	Vérifie types et composants (paquet `@astrojs/check` et `typescript`)
`npx astro add <intégration>`	Installe et configure une intégration

Configuration minimale

astro.config.mjs :

// @ts-check
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://exemple.com',
  trailingSlash: 'always',
});

site est nécessaire pour le sitemap, les URL canoniques et les flux RSS. trailingSlash fixe la forme des URL (always, never ou ignore) : choisir une valeur et s’y tenir.

Variables d’environnement

cat > .env <<'ENV'
SITE_URL=https://exemple.com
PUBLIC_ANALYTICS_ID=abc123
ENV

---
const site = import.meta.env.SITE_URL; // serveur uniquement
---

<p>{import.meta.env.PUBLIC_ANALYTICS_ID}</p>
<!-- exposée au navigateur -->

Seules les variables préfixées PUBLIC_ sont envoyées au navigateur. Ne jamais mettre de secret dans une variable PUBLIC_, et ne jamais versionner .env (.gitignore).

Premier changement

src/pages/index.astro :

---
const titre = 'Mon site';
---

<html lang="fr">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{titre}</title>
  </head>
  <body>
    <h1>{titre}</h1>
    <p>Construit avec Astro.</p>
  </body>
</html>

Le code entre les lignes --- (le « frontmatter ») s’exécute à la compilation (ou sur le serveur), jamais dans le navigateur.

Dépannage

Symptôme	Piste
`Cannot find package 'astro'`	`npm install` non exécuté
Version de Node.js refusée	`node --version` : installer une version prise en charge (voir Node.js : gérer les versions)
`Port 4321 is in use`	Autre instance : `sudo ss -tlnp \| grep 4321` ; Astro propose un autre port
Page blanche en développement	Erreur affichée dans le terminal ou la console du navigateur
`import.meta.env.X` vaut `undefined`	Variable absente de `.env`, ou sans préfixe `PUBLIC_` côté navigateur

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Ubuntu : seule compte la version de Node.js installée. Pour le déploiement sur un serveur, voir Rendu et déploiement.

Pour aller plus loin

Documentation : docs.astro.build
Suite : Pages et routes