Configurer Astro

Personnalisez le fonctionnement d’Astro en ajoutant un fichier astro.config.mjs dans votre projet. C’est un fichier commun dans les projets Astro, et tous les exemples officiels de modèles et de thèmes sont livrés avec un fichier par défaut.

📚 Lisez la doc de référence de l’API d’Astro (EN) pour une vue d’ensemble de toutes les options de configuration supportées.

Un fichier de configuration Astro valide exporte sa configuration en utilisant l’export default, en utilisant l’aide defineConfig recommandée :

import { defineConfig } from 'astro/config'

export default defineConfig({
  // vos options de configuration ici...
  // https://docs.astro.build/fr/reference/configuration-reference/
})

L’utilisation de defineConfig() est recommandé pour obtenir l’aide sur les types utilisés dans votre éditeur de code (IDE), mais elle est aussi optionnelle. Un fichier de configuration minimal valide pourrait ressembler à ça :

// Exemple : Fichier de configuration minimal, vide
export default {}

Astro supporte plusieurs formats de fichiers pour son fichier de configuration JavaScript : astro.config.js, astro.config.mjs, astro.config.cjs et astro.config.ts. Nous recommandons d’utiliser .mjs dans la plupart des cas où .ts si vous voulez écrire du TypeScript dans votre fichier de configuration.

Le chargement du fichier de configuration TypeScript est géré par tsm respectera les options tsconfig de votre projet.

Astro va automatiquement essayer de résoudre un fichier de configuration nommé astro.config.mjs à la racine du projet. Si aucun fichier de configuration n’est trouvé à la racine de votre projet, les options par défaut d’Astro seront utilisées.

# Exemple : Lit votre configuration à partir de ./astro.config.mjs
astro build

Vous pouvez explicitement définir un fichier de configuration à utiliser avec l’option --config depuis l’interface de commande en ligne CLI. Cette option est toujours relative au répertoire de travail actuel dans lequel vous avez lancé la commande astro.

# Exemple : Lit votre configuration à partir de ce fichier
astro build --config mon-fichier-config.js

Astro recommande d’utiliser l’aide defineConfig() dans votre fichier de configuration. defineConfig() fournit une autocomplétion automatique dans votre IDE. Les éditeurs comme VSCode sont capables de lire les définitions de type TypeScript d’Astro et de fournir des indications de type JSDoc automatiques, même si votre fichier de configuration n’est pas écrit en TypeScript.

import { defineConfig } from 'astro/config'

export default defineConfig({
  // vos options de configuration ici...
  // https://docs.astro.build/fr/reference/configuration-reference/
})

Vous pouvez également fournir des définitions de type manuellement à VSCode, en utilisant cette notation JSDoc :

 export default /** @type {import('astro').AstroUserConfig} */ ({
  // vos options de configuration ici...
  // https://docs.astro.build/fr/reference/configuration-reference/
}

Si vous fournissez un chemin relatif à root ou à l’option --root, Astro résoudera ce chemin par rapport au répertoire de travail actuel où vous avez lancé la commande astro.

import { defineConfig } from 'astro/config'

export default defineConfig({
  // Cherches vers le répertoire "./foo" dans le répertoire de travail actuel
  root: 'foo'
})

Astro va chercher toutes les autres chaînes relatives de fichiers et de répertoires par rapport à la racine du projet :

import { defineConfig } from 'astro/config'

export default defineConfig({
  // Se dirige vers le répertoire "./foo" dans le répertoire de travail actuel
  root: 'foo',
  // Se dirige vers le répertoire "./foo/public" dans le répertoire de travail actuel
  publicDir: 'public',
})

Pour référencer un fichier ou un répertoire relatif au fichier de configuration, utilisez import.meta.url (sauf si vous écrivez un fichier common.js astro.config.cjs).

import { defineConfig } from 'astro/config'

export default defineConfig({
  // Se dirige vers le répertoire "./foo", relatif à ce fichier de configuration
  root: new URL("./foo", import.meta.url).toString(),
  // Se dirige vers le répertoire "./public", relatif à ce fichier de configuration
  publicDir: new URL("./public", import.meta.url).toString(),
})

Pour le code qu’Astro traite, comme les fichiers JavaScript ou CSS importés, vous pouvez personnaliser les noms de fichiers de sortie en utilisant entryFileNames (EN), chunkFileNames (EN), et assetFileNames (EN) dans une entrée vite.build.rollupOptions de votre fichier astro.config.*.

import { defineConfig } from 'astro/config'

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          entryFileNames: 'entry.[hash].mjs',
          chunkFileNames: 'chunks/chunk.[hash].mjs',
          assetFileNames: 'assets/asset.[hash][extname]',
        },
      },
    },
  },
})

Cela peut être utile si vous avez des scripts dont les noms peuvent être affectés par des bloqueurs de publicité (par exemple ads.js ou google-tag-manager.js).

Astro évalue les fichiers de configuration avant de charger vos autres fichiers. Ainsi, vous ne pouvez pas utiliser import.meta.env pour accéder aux variables d’environnement qui ont été définies dans les fichiers .env.

Vous pouvez utiliser process.env dans un fichier de configuration pour accéder à d’autres variables d’environnement, comme celles définies par le CLI.

Vous pouvez également utiliser l’aide loadEnv de Vite (EN) pour charger manuellement les fichiers .env.

import { loadEnv } from "vite";
const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

📚 Lisez la documentation de référence sur la configuration de l’API d’Astro (EN) pour une vue d’ensemble des options de configuration supportées.