astro.config.mjs : guide pratique de configuration Astro

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

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 :

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

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 :

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.