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 pour une vue d’ensemble de toutes les options de configuration supportées.

Le Fichier de Configuration d’Astro

Titre de la section Le Fichier de Configuration d’Astro

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

astro.config.mjs

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 {}

Types de Fichier de Configuration Supportés

Titre de la section Types de Fichier de Configuration Supportés

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.

Résolution du fichier de configuration

Titre de la section Résolution du fichier de configuration

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

Autocomplétion de configuration

Titre de la section Autocomplétion de configuration

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.

astro.config.mjs

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 :

astro.config.mjs

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

Référencement des fichiers relatifs

Titre de la section Référencement des fichiers relatifs

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.

astro.config.mjs

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 :

astro.config.mjs

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).

astro.config.mjs

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(),
})

Note

Les propriétés import.meta spécifiques à Vite, comme import.meta.env ou import.meta.glob, ne sont pas accessibles depuis votre fichier de configuration. Nous recommandons des alternatives comme dotenv ou fast-glob pour ces cas d’utilisation respectifs. En outre, les alias de chemin tsconfig ne seront pas résolus. Utilisez des chemins relatifs pour les importations de modules dans ce fichier.

Personnalisation des noms de fichiers de sortie

Titre de la section Personnalisation des noms de fichiers de sortie

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.*.

astro.config.mjs

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).

Variables d’Environment

Titre de la section Variables d’Environment

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.

Note

pnpm ne vous permet pas d’importer des modules qui ne sont pas directement installés dans votre projet. Si vous utilisez pnpm, vous devrez installer vite pour utiliser l’aide loadEnv.

pnpm add vite --save-dev

astro.config.mjs

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

Référence de configuration

Titre de la section Référence de configuration

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