Référence de configuration

La référence suivante couvre toutes les options de configuration prises en charge dans Astro. Pour en savoir plus sur la configuration d’Astro, lisez notre guide sur la configuration d’Astro.

import { defineConfig } from 'astro/config'

export default defineConfig({
  // Vos options de configuration ici...
})

Type: string
CLI: --root
Par défaut: "." (répertoire de travail actuel)

Vous ne devez fournir cette option que si vous exécutez la commande CLI astro dans un répertoire autre que le répertoire racine du projet. Habituellement, cette option est fournie via le CLI au lieu du fichier de configuration Astro, car Astro doit connaître la racine de votre projet avant de pouvoir localiser votre fichier de configuration.

Si vous fournissez un chemin relatif (ex: --root: './my-project') Astro va le résoudre par rapport à votre répertoire de travail actuel.

{
  root: './my-project-directory'
}

$ astro build --root ./my-project-directory

Type: string
Par défaut: "./src"

Définissez le répertoire à partir duquel Astro lira votre site.

La valeur peut être soit un chemin absolu du système de fichiers, soit un chemin relatif à la racine du projet.

{
  srcDir: './www'
}

Type: string
Par défaut: "./public"

Définissez le répertoire de vos ressources statiques. Les fichiers de ce répertoire sont servis à / pendant le développement et copiés dans votre répertoire de build pendant la phase de build. Ces fichiers sont toujours servis ou copiés tels quels, sans transformation ni regroupement.

La valeur peut être soit un chemin absolu du système de fichiers, soit un chemin relatif à la racine du projet.

{
  publicDir: './my-custom-publicDir-directory'
}

Type: string
Par défaut: "./dist"

Définissez le répertoire dans lequel astro build écrit votre version finale.

La valeur peut être soit un chemin absolu du système de fichiers, soit un chemin relatif à la racine du projet.

{
  outDir: './my-custom-build-directory'
}

Type: string

Votre URL finale déployée. Astro utilise cette URL complète pour générer votre sitemap et vos URL canoniques dans votre version finale. Il est fortement recommandé de définir cette configuration pour tirer le meilleur parti d’Astro.

{
  site: 'https://www.my-site.dev'
}

Type: string

Le chemin de base vers lequel vous effectuez le déploiement. Astro correspondra à ce nom de chemin d’accès pendant le développement afin que votre expérience de développement corresponde la plus possible à votre environnement de build. Dans l’exemple c-dessous, astro dev démarrera votre serveur à /docs.

{
  base: '/docs'
}

Type: 'always' | 'never' | 'ignore'
Par défaut: 'ignore'

Définissez la route correspondante au comportement du serveur dev. Choisissez parmi les options suivantes :

• 'always' - Ne correspond qu’aux URL qui incluent un slash de fin (ex: “/foo/“)
• 'never' - Ne correspond à aucune URL incluant un slash de fin (ex: “/foo”)
• 'ignore' - Correspond aux URL qu’il existe ou non un ”/” à la fin.

Utilisez cette option de configuration si votre hôte de production a une gestion stricte du fonctionnement ou du non-fonctionnement des slashs finaux.

Vous pouvez également le définir si vous préférez être vous-même plus strict, afin que les URL avec ou sans slash à la fin ne fonctionnent pas pendant le développement.

{
  // Exemple: Exiger un slash final pendant le développement
  trailingSlash: 'always'
}

Voir également :

• buildOptions.format

Type: AstroIntegration

Déployez-le sur votre serveur préféré, sans serveur ou hôte périphérique avec des adaptateurs de build. Importez l’un de nos adaptateurs pour Netlify, Vercel, et plus encore pour activer Astro SSR.

Voir notre guide de rendu côté serveur pour en savoir plus sur le SSR, et nos guides de déploiement pour une liste complète d’hôtes.

import netlify from '@astrojs/netlify/functions';
{
  // Exemple: Construire pour un déploiement sans serveur Netlify
   adapter: netlify(),
}

Voir également :

• output

Type: 'static' | 'server'
Par défaut: 'static'

Spécifie la cible de sortie pour les builds.

• ‘static’ - Construire un site statique à déployer sur n’importe quel hôte statique.
• ‘server’ - Création d’une application à déployer sur un hôte prenant en charge le SSR (rendu côté serveur).

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static'
})

Voir également :

• adapter

Type: ('file' | 'directory')
Par défaut : 'directory'

Contrôlez le format de fichier de sortie de chaque page.

• Si la valeur est ‘file’, Astro générera un fichier HTML (ex: “/foo.html”) pour chaque page.
• Si la valeur est ‘directory’, Astro générera un répertoire avec un fichier imbriqué index.html (ex: “/foo/index.html”) pour chaque page.

{
  build: {
    // Exemple: Générer `page.html` au lieu de `page/index.html` durant le build.
    format: 'file'
  }
}

Le paramètre build.format contrôle ce à quoi Astro.url est défini pendant la compilation. Quand il est défini sur:

• directory - L’Astro.url.pathname inclura un slash pour imiter le comportement des dossiers; c.-à-d. /foo/.
• file - L’Astro.url.pathname inclura .html; c.-à-d. /foo.html.

Cela signifie que lorsque vous créez des URL relatives en utilisant new URL('./relative', Astro.url), vous obtiendrez un comportement cohérent entre dev et build.

Personnalisez le serveur Astro dev, utilisé par astro dev et astro preview.

{
  server: { port: 1234, host: true }
}

Pour définir une configuration différente basée sur la commande run (“dev”, “preview”) une fonction peut également être passée à cette option de configuration.

{
  // Exemple: Utiliser la syntaxe de fonction pour personnaliser le serveur en fonction de la commande
  server: (command) => ({ port: command === 'dev' ? 3000 : 4000 })
}

Type: string | boolean
Par défaut: false

Définir les adresses IP réseau sur lesquelles le serveur doit écouter (c.-à-d. les adresses IP non locales).

• false - ne pas exposer sur une adresse IP réseau
• true - écouter toutes les adresses, y compris les adresses LAN et publiques
• [custom-address] - exposer sur une adresse IP réseau à [custom-address] (ex: 192.168.0.1)

Type: number
Par défaut: 3000

Définissez le port sur lequel le serveur doit écouter.

Si le port donné est déjà utilisé, Astro va automatiquement essayer le prochain port disponible.

{
  server: { port: 8080 }
}

Type: boolean
Par défaut: false

Contrôler si les pages de projet Markdown doivent être incluses dans la construction.

Une page Markdown est considérée comme un brouillon si elle inclut draft: true dans son avant-propos. Les brouillons de pages sont toujours inclus et visibles pendant le développement (astro dev) mais par défaut, ils ne seront pas inclus dans votre build final.

{
  markdown: {
    // Exemple: Inclure tous les brouillons dans votre version finale
    drafts: true,
  }
}

Type: Partial<ShikiConfig>

Options de configuration Shiki. Voir la documentation de configuration Markdown pour l’utilisation.

Type: 'shiki' | 'prism' | false
Défaut: shiki

Quel surligneur de syntaxe utiliser, le cas échéant.

• shiki - utiliser le surligneur Shiki
• prism - utiliser le surligneur Prism
• false - ne pas appliquer la mise en évidence de la syntaxe.

{
  markdown: {
    // Exemple: Passer à l’utilisation de prism pour la mise en évidence de la syntaxe dans Markdown
    syntaxHighlight: 'prism',
  }
}

Type: RemarkPlugins

Passer un plugin remark pour personnaliser la façon dont votre Markdown est construit. Vous pouvez importer et appliquer la fonction du plugin (recommandé), ou passer le nom du plugin comme une chaîne de caractère.

{
  markdown: {
    remarkPlugins: [remarkToc]
  }
}

Type: RehypePlugins

Passez un plugin rehype pour personnaliser la manière dont le résultat HTML de sortie de votre Markdown sera traité. Vous pouvez importer et appliquer la fonction du plugin (recommandé), ou juste pass le nom du plugin en tant que chaine de caractères.

import rehypeMinifyHtml from 'rehype-minify';
{
  markdown: {
    rehypePlugins: [rehypeMinifyHtml]
  }
}

Type : boolean
Par défaut : false

Astro applique par défaut les plugins Markdown de GitHub et Smartypants. Quand vous ajoutez votre propre plugin remark ou rehype, vous pouvez préserver ces plugins par défaut en paramétrant l’option extendDefaultPlugins sur true

{
  markdown: {
    extendDefaultPlugins: true,
     remarkPlugins: [exampleRemarkPlugin],
    rehypePlugins: [exampleRehypePlugin],
  }
}

Type: RemarkRehype

Passez les options à remark-rehype.

{
  markdown: {
    // Exemple: Traduire le texte du footer dans un autre langage, ce sont les valeurs anglaises par défaut.
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to content"},
  },
};

Étendez Astro avec des intégrations personnalisées. Les intégrations sont votre guichet unique pour ajouter la prise en charge du framework (comme Solid.js), de nouvelles fonctionnalités (comme les sitemaps) et de nouvelles bibliothèques (comme Partytown et Turbolinks).

Lisez notre Guide d’intégration pour vous aider à débuter avec les intégrations Astro.

import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // Exemple: Ajouter la prise en charge de React + Tailwind par Astro
  integrations: [react(), tailwind()]
}

Passez des options de configuration supplémentaires à Vite. Utile lorsque Astro ne prend pas en charge certaines configurations avancées dont vous pourriez avoir besoin.

Regardez la documentation complète de l’objet de configuration de vite sur vitejs.dev.

{
  vite: {
    ssr: {
      // Exemple: Forcer un package cassé à passer outre le processus SSR si besoin.
      external: ['broken-npm-package'],
    }
  }
}

{
  vite: {
    // Exemple: Ajout des plugins personnalisés vite directement à votre projet Astro.
    plugins: [myPlugin()],
  }
}

Pour aider certains utilisateurs à migrer entre les versions d’Astro, nous introduisons occasionnellement des options héritées. Ces options vous permettent d’opter pour un comportement déprécié ou autrement dépassé d’Astro dans la dernière version, afin que vous puissiez continuer à mettre à jour et profiter des nouvelles versions d’Astro.

Type: boolean
Par défaut: false

Activer le support de la pre-v1.0 Astro pour les composants et expressions JSX dans les fichiers Markdown .md. Dans Astro 1.0.0-rc, ce comportement original a été supprimé par défaut, en faveur de notre nouvelle intégration MDX (EN).

Pour activer ce comportement, définissez legacy.astroFlavoredMarkdown sur true dans votre fichier de configuration astro.config.mjs.

{
  legacy: {
    // Exemple: Ajout de la prise en charge des anciennes fonctionnalités Markdown
    astroFlavoredMarkdown: true,
  },
}