## 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 : ```bash 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é : ```bash cd mon-projet-astro ``` ## Arborescence à connaître ```text 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 ```bash 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é) : ```astro --- const titre = "Bienvenue sur Astro"; --- {titre}

{titre}

Premier rendu statique, prêt pour le SEO.

``` 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 ```bash 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 : ```javascript 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 `site`** en production : URLs relatives cassées dans le RSS ou le SEO. ## Prochaines étapes 1. Ajouter une intégration UI (React, Vue) uniquement si nécessaire. 2. Structurer le contenu via **content collections** pour un blog ou une doc. 3. Choisir un hébergeur compatible static ou SSR — quand choisir Astro pour un site statique. 4. 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émarrage

Installer Astro : prérequis, structure, premières commandes