## Le fichier qui arbitre toute votre stack Dans un projet Astro, `astro.config.mjs` n'est pas un détail administratif. C'est le point où vous décidez du **mode de rendu**, des **intégrations**, de l'**URL publique** et parfois de la **stratégie d'images**. Une configuration floue se paie au moment du premier déploiement : chemins cassés, double hydratation, build CI différent du local. Si vous débutez, installez d'abord le projet avec le guide d'installation Astro. Ce article se concentre sur les réglages qui tiennent dans la durée. ## Anatomie du fichier ```javascript import { defineConfig } from "astro/config"; export default defineConfig({ site: "https://exemple.fr", output: "static", integrations: [], }); ``` `defineConfig` apporte l'autocomplétion TypeScript. Le fichier est un module ESM : les imports dynamiques d'intégrations se font en tête de fichier. ## L'option `site` : non négociable en production `site` définit l'origine absolue utilisée pour : - les balises **canonical** ; - le **sitemap** généré ; - certaines **URLs Open Graph** ; - les flux RSS. Sans elle, un déploiement derrière CDN peut générer des liens relatifs incohérents. Renseignez le domaine final, pas l'URL de preview. ## Intégrations : n'ajoutez que le nécessaire Les intégrations officielles couvrent React, Vue, Tailwind, MDX, sitemap, etc. Documentation : guide des intégrations. Exemple avec React : ```javascript import { defineConfig } from "astro/config"; import react from "@astrojs/react"; export default defineConfig({ integrations: [react()], }); ``` Chaque intégration peut modifier le bundler et le comportement de build. Avant d'en empiler cinq, demandez-vous si un composant `.astro` suffit. ## Static, server et hybrid | Mode | Comportement | Cas typique | | --- | --- | --- | | `static` (défaut) | HTML généré au build | Blog, vitrine | | `server` | Rendu à chaque requête | Contenu personnalisé | | `hybrid` | Pages statiques + routes dynamiques | Mix marketing + API | Le rendu hybride est documenté ici : on-demand rendering. Activez `output: "hybrid"` puis marquez les routes dynamiques avec `export const prerender = false`. ## Adaptateurs : le chaînon manquant en SSR Sans adaptateur, Astro ne sait pas où exécuter le serveur. Exemples : - `@astrojs/node` pour un VPS ; - `@astrojs/vercel` ou `@astrojs/netlify` pour le PaaS ; - `@astrojs/cloudflare` pour l'edge. L'adaptateur influence le format de sortie (`dist/`), le handler serverless et parfois le cache. Choisissez-le **avant** de coder des routes dynamiques, pas la veille de la mise en prod. ## Images et performances Astro peut déléguer l'optimisation d'images au service de build. Configurez : - domaines autorisés pour les images distantes ; - formats modernes (WebP, AVIF) selon l'hébergeur ; - politique de lazy loading par défaut dans les layouts. Ces réglages impactent directement les **Core Web Vitals** — sujet traité dans Astro et performance en entreprise. ## Variables d'environnement Préfixez les variables exposées au client avec `PUBLIC_` (convention Astro). Les secrets (clés API, tokens) restent côté serveur dans les endpoints ou le rendu SSR. En CI, injectez les mêmes noms que en local via le tableau de plateforme (GitHub Actions, DevPush, etc.) pour éviter le classique « ça marche chez moi ». ## Configuration par environnement Pattern courant : ```javascript import { defineConfig } from "astro/config"; const isDev = process.env.NODE_ENV === "development"; export default defineConfig({ site: process.env.PUBLIC_SITE_URL, devToolbar: { enabled: isDev }, }); ``` Évitez les branches `if (prod)` dispersées dans le code applicatif : centralisez dans la config ou un module `src/env.ts` validé avec Zod. ## Checklist avant merge 1. `npm run build` passe en CI avec la même version Node que le README. 2. `site` pointe vers le domaine de production. 3. Chaque intégration est justifiée dans le README technique. 4. L'adaptateur correspond à l'hébergeur réel. 5. Les routes dynamiques sont listées et testées. ## Erreurs classiques - **Oublier l'adaptateur** en mode server ; - **Dupliquer** Tailwind dans PostCSS et via `@astrojs/tailwind` ; - **Importer** un composant client dans le layout racine sans besoin ; - **Mélanger** `base` et `site` sans comprendre le déploiement en sous-chemin. ## Conclusion Maîtriser `astro.config.mjs`, c'est anticiper le déploiement dès le premier commit. Astro récompense les projets sobres : peu d'intégrations, un mode de rendu clair, une URL publique explicite. Le reste — contenu, SEO, UX — peut alors s'appuyer sur une base technique stable. Pour le contexte stratégique Cloudflare + Astro : notre analyse de l'acquisition. Documentation officielle : référence de configuration.

#configuration

astro.config.mjs : guide pratique de configuration Astro