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

Options de niveau supérieur

site

Type : string

Il s’agit de votre URL finale déployée. Astro utilise cette URL complète pour générer votre plan de site 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.mon-site.dev'
}

base

Type : string

Le chemin de base vers lequel déployer. Astro utilisera ce chemin comme racine de vos pages et de vos ressources à la fois en développement et en production.

Dans l’exemple ci-dessous, astro dev démarrera votre serveur à l’adresse /docs.

{
  base: '/docs'
}

Lorsque vous utilisez cette option, toutes vos importations de ressources statiques et toutes vos URL doivent ajouter cette base comme préfixe. Vous pouvez accéder à cette valeur via import.meta.env.BASE_URL.

La valeur de import.meta.env.BASE_URL sera déterminée par votre configuration trailingSlash, quelle que soit la valeur que vous avez définie pour base.

Une barre oblique finale est toujours incluse quand l’option trailingSlash: "always" est définie. Au contraire, quand l’option trailingSlash: "never" est définie, BASE_URL n’inclura pas de barre oblique finale, même si base en inclut une.

De plus, Astro manipulera en interne la valeur configurée de config.base avant de la rendre disponible aux intégrations. La valeur de config.base telle que lue par les intégrations sera également déterminée par votre configuration trailingSlash de la même manière.

Dans l’exemple ci-dessous, les valeurs de import.meta.env.BASE_URL et config.base une fois traitées seront toutes deux /docs :

{
   base: '/docs/',
   trailingSlash: "never"
}

Dans l’exemple ci-dessous, les valeurs de import.meta.env.BASE_URL et config.base une fois traitées seront toutes deux /docs/ :

{
   base: '/docs',
   trailingSlash: "always"
}

trailingSlash

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

Définissez le comportement de correspondance des routes pour le serveur de développement. Choisissez parmi les options suivantes :

'always' - Faire correspondre uniquement les URL incluant une barre oblique finale (par exemple : « /foo/ »)
'never' - Ne jamais faire correspondre les URL qui incluent une barre oblique finale (par exemple : « /foo »)
'ignore' - Faire correspondre les URL, qu’il existe ou non une barre oblique finale (/)

Utilisez cette option de configuration si votre hôte de production gère strictement le fonctionnement ou le non-fonctionnement des barres obliques finales.

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

{
  // Exemple : Exiger une barre oblique finale pendant le développement
  trailingSlash: 'always'
}

Voir aussi :

build.format

redirects

Type : Record.<string, RedirectConfig>
Par défaut : {}

Ajouté à la version : astro@2.9.0

Spécifie le mappage des redirections où la clé est la route à rechercher et la valeur est le chemin vers lequel rediriger.

Vous pouvez rediriger des routes statiques et dynamiques, mais uniquement vers le même type de route. Par exemple, vous ne pouvez pas avoir de redirection '/article': '/blog/[...slug]'.

{
  redirects: {
    '/ancien': '/nouveau',
    '/blog/[...slug]': '/articles/[...slug]',
  }
}

Pour les sites générés statiquement sans adaptateur installé, cela produira une redirection client à l’aide d’une balise <meta http-equiv="refresh"> qui ne prend pas en charge les codes d’état.

Lors de l’utilisation de SSR ou avec un adaptateur statique en mode output: "static", les codes d’état sont pris en charge. Astro servira les requêtes GET redirigées avec un statut 301 et utilisera un statut 308 pour toute autre méthode de requête.

Vous pouvez personnaliser le code d’état de redirection à l’aide d’un objet dans la configuration de redirection :

{
  redirects: {
    '/autre': {
      status: 302,
      destination: '/endroit',
    },
  }
}

output

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

Spécifie la cible de sortie des générations.

'static' - Création d’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 SSR (rendu côté serveur).
'hybrid' - Création d’un site statique avec quelques pages générées côté serveur.

import { defineConfig } from 'astro/config';

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

Voir aussi :

adapter

adapter

Type : AstroIntegration

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

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

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

Voir aussi :

output

integrations

Type : AstroIntegration[]

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

Lisez notre Guide sur les intégrations pour obtenir de l’aide pour démarrer avec les intégrations Astro.

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

root

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

Vous devez renseigner cette option seulement si vous exécutez les commandes CLI astro dans un répertoire autre que le répertoire racine du projet. Habituellement, cette option est définie via le CLI au lieu du fichier de configuration Astro, car Astro a besoin de connaître la racine de votre projet avant de pouvoir localiser votre fichier de configuration.

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

Exemples

{
  root: './mon-répertoire-de-projet'
}

$ astro build --root ./mon-répertoire-de-projet

srcDir

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

Définit 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'
}

publicDir

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

Définit le répertoire de vos ressources statiques. Les fichiers de ce répertoire sont servis dans / pendant le développement et copiés dans votre répertoire de sortie pendant la construction. 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: './mon-répertoire-publicDir-personnalisé'
}

outDir

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

Définit 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'
}

Voir aussi :

build.server

cacheDir

Type : string
Par défaut : "./node_modules/.astro"

Définit le répertoire pour la mise en cache des artefacts de construction. Les fichiers de ce répertoire seront utilisés dans les versions ultérieures pour accélérer le temps de construction.

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

{
  cacheDir: './mon-répertoire-de-cache-personnalisé'
}

compressHTML

Type : boolean
Par défaut : true

Il s’agit d’une option permettant de minimiser votre sortie HTML et de réduire la taille de vos fichiers HTML.

Par défaut, Astro supprime des composants .astro les espaces présents dans votre HTML, y compris les sauts de ligne, sans perte. Certains espaces peuvent être conservés si nécessaire pour préserver le rendu visuel de votre HTML. Cela se produit à la fois en mode développement et dans la version finale.

Pour désactiver la compression HTML, définissez compressHTML sur false.

{
  compressHTML: false
}

scopedStyleStrategy

Type : 'where' | 'class' | 'attribute'
Par défaut : 'attribute'

Ajouté à la version : astro@2.4

Spécifie la stratégie utilisée pour limiter la portée des styles dans les composants Astro. Choisissez parmi :

'where' - Utilisez les sélecteurs :where, n’entraînant aucune augmentation de spécificité.
'class' - Utilisez des sélecteurs basés sur les classes, provoquant une augmentation de spécificité (+1).
'attribute' - Utilisez les attributs data-, provoquant une augmentation de spécificité (+1).

L’utilisation de 'class' est utile lorsque vous voulez vous assurer que les sélecteurs d’éléments au sein d’un composant Astro remplacent les styles globaux par défaut (par exemple à partir d’une feuille de style globale). L’utilisation de 'where' vous donne plus de contrôle sur la spécificité, mais nécessite que vous utilisiez des sélecteurs, des calques et d’autres outils de plus grande spécificité pour contrôler quels sélecteurs sont appliqués. L’utilisation d’'attribut' est utile lorsque vous manipulez l’attribut class des éléments et que vous devez éviter les conflits entre votre propre logique de style et l’application des styles par Astro.

security

Type : boolean
Par défaut : {}

Ajouté à la version : astro@4.9.0

Active les mesures de sécurité pour un site web Astro.

Ces fonctionnalités n’existent que pour les pages rendues à la demande (SSR) en mode serveur (server) ou pour les pages qui refusent le prérendu en mode hybride (hybrid).

export default defineConfig({
  output: "server",
  security: {
    checkOrigin: true
  }
})

security.checkOrigin

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.9.0

Lorsqu’il est activé, vérifie que l’en-tête « origin », automatiquement transmis par tous les navigateurs modernes, correspond à l’URL envoyée par chaque Request. Ceci est utilisé pour fournir une protection contre la falsification de requêtes intersites (CSRF).

La vérification de l’en-tête « origin » est exécutée uniquement pour les pages rendues à la demande, et uniquement pour les requêtes POST, PATCH, DELETE et PUT avec l’un des en-têtes content-type suivants :'application/ x-www-form-urlencoded', 'multipart/form-data', 'text/plain'.

Si l’en-tête « origin » ne correspond pas au chemin d’accès de la requête (pathname), Astro renverra un code d’état 403 et n’affichera pas la page.

vite

Type : ViteUserConfig

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

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

Exemples

{
  vite: {
    ssr: {
      // Exemple : Forcer un paquet défectueux à ignorer le traitement SSR, si nécessaire
      external: ['paquet-npm-cassé'],
    }
  }
}

{
  vite: {
    // Exemple : Ajouter des extensions personnalisées à Vite directement dans votre projet Astro
    plugins: [monExtension()],
  }
}

Options de construction

build.format

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

Contrôlez le format de fichier de sortie de chaque page. Cette valeur peut être définie par un adaptateur pour vous.

'file' : Astro générera un fichier HTML nommé pour chaque route de page. (par exemple, src/pages/about.astro et src/pages/about/index.astro construisent tous deux le fichier /about.html)
'directory' : Astro générera un répertoire avec un fichier index.html imbriqué pour chaque page. (par exemple, src/pages/about.astro et src/pages/about/index.astro construisent tous deux le fichier /about/index.html)
'preserve' : Astro générera des fichiers HTML exactement tels qu’ils apparaissent dans votre dossier source. (par exemple, src/pages/about.astro construit /about.html et src/pages/about/index.astro construit le fichier /about/index.html)

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

Effet sur Astro.url

La définition de build.format contrôle ce sur quoi Astro.url est défini pendant la construction. Lorsqu’il est défini sur :

directory - La valeur d’Astro.url.pathname inclura une barre oblique finale pour imiter le comportement du dossier ; c’est-à-dire /foo/.
file - La valeur d’Astro.url.pathname inclura .html ; c’est-à-dire /foo.html.

Cela signifie que lorsque vous créez des URL relatives à l’aide de new URL('./relative', Astro.url), vous obtiendrez un comportement cohérent entre le développement et la construction.

Pour éviter les incohérences avec le comportement des barres obliques finales en développement, vous pouvez restreindre l’option trailingSlash à 'always' ou 'never' selon votre format de build :

directory - Définissez trailingSlash: 'always'
file - Définissez trailingSlash: 'never'

build.client

Type : string
Par défaut : './dist/client'

Contrôle le répertoire de sortie de vos fichiers CSS et JavaScript, côté client, avec output: 'server' ou output: 'hybrid' uniquement. outDir contrôle l’endroit où le code est construit.

Cette valeur est relative à outDir.

{
  output: 'server', // ou 'hybrid'
  build: {
    client: './client'
  }
}

build.server

Type : string
Par défaut : './dist/server'

Contrôle le répertoire de sortie du JavaScript côté serveur lors de la construction en mode SSR.

Cette valeur est relative à outDir.

{
  build: {
    server: './server'
  }
}

build.assets

Type : string
Par défaut : '_astro'

Ajouté à la version : astro@2.0.0

Spécifie le répertoire dans la sortie de construction où doivent résider les ressources générées par Astro (JS et CSS regroupés par exemple).

{
  build: {
    assets: '_custom'
  }
}

Voir aussi :

outDir

build.assetsPrefix

Type : string | Record.<string, string>
Par défaut : undefined

Ajouté à la version : astro@2.2.0

Spécifie le préfixe des liens des ressources générées par Astro. Cela peut être utilisé si les ressources sont servies à partir d’un domaine différent de celui du site actuel.

Cela nécessite de télécharger les ressources de votre dossier local ./dist/_astro vers un dossier /_astro/ correspondant sur le domaine distant. Pour renommer le chemin _astro, spécifiez un nouveau répertoire dans build.assets.

Pour récupérer toutes les ressources téléchargées sur le même domaine (par exemple https://cdn.example.com/_astro/...), définissez assetsPrefix sur le domaine racine sous forme de chaîne de caractères (quelle que soit votre configuration de base) :

{
  build: {
    assetsPrefix: 'https://cdn.example.com'
  }
}

Ajouté dans : astro@4.5.0

Vous pouvez également transmettre un objet à assetsPrefix pour spécifier un domaine différent pour chaque type de fichier. Dans ce cas, une propriété fallback est requise et sera utilisée par défaut pour tous les autres fichiers.

{
  build: {
    assetsPrefix: {
      'js': 'https://js.cdn.example.com',
      'mjs': 'https://js.cdn.example.com',
      'css': 'https://css.cdn.example.com',
      'fallback': 'https://cdn.example.com'
    }
  }
}

build.serverEntry

Type : string
Par défaut : 'entry.mjs'

Spécifie le nom de fichier du point d’entrée du serveur lors de la construction en utilisant le mode SSR. Ce point d’entrée dépend généralement de l’hôte sur lequel vous déployez et sera défini par votre adaptateur pour vous.

Notez qu’il est recommandé que ce fichier se termine par .mjs afin que le runtime détecte que le fichier est un module JavaScript.

{
  build: {
    serverEntry: 'main.mjs'
  }
}

build.redirects

Type : boolean
Par défaut : true

Ajouté à la version : astro@2.6.0

Spécifie si les redirections seront générées au format HTML lors de la construction. Cette option s’applique uniquement au mode output: 'static' ; avec SSR, les redirections sont traitées de la même manière que toutes les réponses.

Cette option est principalement destinée à être utilisée par les adaptateurs qui ont des fichiers de configuration spéciaux pour les redirections et qui n’ont pas besoin/ne veulent pas de redirections basées sur HTML.

{
  build: {
    redirects: false
  }
}

build.inlineStylesheets

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

Ajouté à la version : astro@2.6.0

Contrôle si les styles du projet sont envoyés au navigateur dans un fichier CSS séparé ou intégrés dans des balises <style>. Choisissez parmi les options suivantes :

'always' - les styles du projet sont intégrés dans des balises <style>
'auto' - seules les feuilles de style plus petites que la valeur de ViteConfig.build.assetsInlineLimit (par défaut : 4 Ko) sont intégrées. Sinon, les styles du projet sont envoyés dans des feuilles de style externes.
'never' - les styles du projet sont envoyés dans des feuilles de style externes

{
  build: {
    inlineStylesheets: `never`,
  },
}

Options du serveur

Personnalise le serveur de développement Astro, utilisé à la fois par astro dev et astro preview.

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

Pour définir une configuration différente en fonction de l’exécution de la commande (dev, preview), une fonction peut également être transmise à cette option de configuration.

{
  // Exemple : Définir une fonction pour personnaliser la configuration suivant la commande utilisée
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 })
}

server.host

Type : string | boolean
Par défaut : false

Ajouté à la version : astro@0.24.0

Définit les adresses IP réseau sur lesquelles le serveur doit écouter (c’est-à-dire les adresses IP non locales).

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

server.port

Type : number
Par défaut : 4321

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

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

{
  server: { port: 8080 }
}

server.open

Type : string | boolean
Par défaut : false

Ajouté à la version : astro@4.1.0

Contrôle si le serveur de développement doit ouvrir une fenêtre dans votre navigateur au démarrage.

Passez une URL complète (par exemple "http://example.com") ou un chemin d’accès (par exemple "/about") pour spécifier l’URL à ouvrir.

{
  server: { open: "/about" }
}

server.headers

Type : OutgoingHttpHeaders
Par défaut : {}

Ajouté à la version : astro@1.7.0

Définit les en-têtes de réponse HTTP personnalisés à envoyer dans astro dev et astro preview.

Options de la barre d’outils de développement

devToolbar.enabled

Type : boolean
Par défaut : true

Détermine s’il faut activer la barre d’outils de développement d’Astro. Cette barre d’outils vous permet d’inspecter vos îles de pages, de consulter des audits utiles sur les performances et l’accessibilité, et bien plus encore.

Cette option s’étend à l’ensemble du projet, pour désactiver uniquement la barre d’outils pour vous-même, exécutez npm run astro preferences disable devToolbar. Pour désactiver la barre d’outils pour tous vos projets Astro, exécutez npm run astro preferences disable devToolbar --global.

Options de préchargement

Type : boolean | object

Active le préchargement des liens sur votre site afin de fournir des transitions de page plus rapides. (Activé par défaut sur les pages utilisant le routeur <ViewTransitions />. Définissez prefetch: false pour désactiver ce comportement.)

Cette configuration ajoute automatiquement un script de préchargement à chaque page du projet vous donnant accès à l’attribut data-astro-prefetch. Ajoutez cet attribut à n’importe quel lien <a /> sur votre page pour activer le préchargement pour cette page.

<a href="/about" data-astro-prefetch>À propos</a>

Personnalisez davantage le comportement par défaut du préchargement à l’aide des options prefetch.defaultStrategy et prefetch.prefetchAll.

Consultez le Guide sur le préchargement pour plus d’informations.

prefetch.prefetchAll

Type : boolean

Active le préchargement pour tous les liens, y compris ceux sans l’attribut data-astro-prefetch. Cette valeur par défaut est définie sur true lors de l’utilisation du routeur <ViewTransitions />. Sinon, la valeur par défaut est false.

prefetch: {
  prefetchAll: true
}

Lorsqu’elle est définie sur true, vous pouvez désactiver le préchargement individuellement en définissant data-astro-prefetch="false" sur n’importe quel lien individuel.

<a href="/about" data-astro-prefetch="false">À propos</a>

prefetch.defaultStrategy

Type : 'tap' | 'hover' | 'viewport' | 'load'
Par défaut : 'hover'

La stratégie de préchargement par défaut à utiliser lorsque l’attribut data-astro-prefetch est défini sur un lien sans valeur.

'tap' : Précharge juste avant de cliquer sur le lien.
'hover' : Précharge lorsque vous survolez le lien ou que vous lui donner le focus. (défaut)
'viewport' : Précharge lorsque les liens entrent dans la fenêtre.
'load' : Précharge tous les liens de la page une fois la page chargée.

Vous pouvez remplacer cette valeur par défaut et sélectionner une stratégie différente pour n’importe quel lien individuel en définissant une valeur sur l’attribut.

<a href="/about" data-astro-prefetch="viewport">À propos</a>

Options d’images

image.endpoint

Type : string
Par défaut : undefined

Ajouté à la version : astro@3.1.0

Définit le point de terminaison à utiliser pour l’optimisation des images en modes développement et SSR. Définissez le paramètre sur undefined pour utiliser le point de terminaison par défaut.

Le point de terminaison sera toujours injecté dans /_image.

{
  image: {
    // Exemple : Utiliser un point de terminaison personnalisé pour les images
    endpoint: './src/image-endpoint.ts',
  },
}

image.service

Type : Object
Par défaut : {entrypoint: 'astro/assets/services/sharp', config?: {}}

Ajouté à la version : astro@2.1.0

Définit le service d’images utilisé pour la prise en charge des ressources d’Astro.

La valeur doit être un objet avec un point d’entrée que le service d’images doit utiliser et, éventuellement, un objet de configuration à transmettre au service.

Le point d’entrée du service peut être soit l’un des services inclus, soit un paquet tiers.

{
  image: {
    // Exemple : Activer le service d'images basé sur Sharp avec une configuration personnalisée
    service: {
       entrypoint: 'astro/assets/services/sharp',
       config: {
         limitInputPixels: false,
      },
     },
  },
}

image.service.config.limitInputPixels

Type : number | boolean
Par défaut : true

Ajouté à la version : astro@4.1.0

Limite ou non la taille des images traitées par le service d’images Sharp.

Définissez le paramètre sur false pour contourner la limite de taille des images par défaut pour le service d’images Sharp et pour traiter des images volumineuses.

image.domains

Type : Array.<string>
Par défaut : {domains: []}

Ajouté à la version : astro@2.10.10

Définit une liste de domaines sources d’images autorisés pour l’optimisation des images à distance. Aucune autre image distante ne sera optimisée par Astro.

Cette option nécessite un tableau de noms de domaine individuels sous forme de chaînes de caractères. Les caractères génériques ne sont pas autorisés. Utilisez plutôt image.remotePatterns pour définir une liste de modèles d’URL source autorisés.

{
  image: {
    // Exemple : Autoriser l'optimisation des images distantes à partir d'un seul domaine
    domains: ['astro.build'],
  },
}

image.remotePatterns

Type : Array.<RemotePattern>
Par défaut : {remotePatterns: []}

Ajouté à la version : astro@2.10.10

Définit une liste de modèles d’URL autorisés comme source d’images pour l’optimisation des images distantes.

remotePatterns peut être configuré avec quatre propriétés :

protocol
hostname
port
pathname

{
  image: {
    // Exemple : autoriser le traitement de toutes les images de votre compartiment aws s3
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}

Vous pouvez utiliser des caractères génériques pour définir les valeurs autorisées pour hostname et pathname comme décrit ci-dessous. Sinon, seules les valeurs exactes fournies seront configurées : hostname :

Commencez avec **. pour autoriser tous les sous-domaines (endsWith).
Commencez avec *. pour autoriser un seul niveau de sous-domaine.

pathname :

Terminez par /** pour autoriser toutes les sous-routes (startsWith).
Terminez par /* pour autoriser un seul niveau de sous-route.

Options de Markdown

markdown.shikiConfig

Type : Partial<ShikiConfig>

Options de configuration de Shiki. Consultez la documentation de configuration de Markdown pour plus d’informations sur son utilisation.

markdown.syntaxHighlight

Type : 'shiki' | 'prism' | false
Par défaut : shiki

Détermine quel colorateur syntaxique utiliser, le cas échéant.

shiki - utilise le colorateur Shiki
prism - utilise le colorateur Prism
false - n’applique aucune coloration syntaxique.

{
  markdown: {
    // Exemple : Utiliser Prism pour la coloration syntaxique dans Markdown
    syntaxHighlight: 'prism',
  }
}

markdown.remarkPlugins

Type : RemarkPlugins

Définit des extensions Remark pour personnaliser la façon dont votre Markdown est construit. Vous pouvez importer et appliquer la fonction de l’extension (recommandé) ou transmettre le nom de l’extension sous forme de chaîne de caractères.

import remarkToc from 'remark-toc';
{
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents"} ] ]
  }
}

markdown.rehypePlugins

Type : RehypePlugins

Définit des extensions Rehype pour personnaliser la façon dont le HTML de sortie de votre Markdown est traité. Vous pouvez importer et appliquer la fonction de l’extension (recommandé) ou transmettre le nom de l’extension sous forme de chaîne de caractères.

import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis]
  }
}

markdown.gfm

Type : boolean
Par défaut : true

Ajouté à la version : astro@2.0.0

Astro utilise GitHub-flavored Markdown par défaut. Pour désactiver cela, définissez l’indicateur gfm sur false :

{
  markdown: {
    gfm: false,
  }
}

markdown.smartypants

Type : boolean
Par défaut : true

Ajouté à la version : astro@2.0.0

Astro utilise le formatteur SmartyPants par défaut. Pour désactiver cela, définissez l’indicateur smartypants sur false :

{
  markdown: {
    smartypants: false,
  }
}

markdown.remarkRehype

Type : RemarkRehype

Transmet des options à remark-rehype.

{
  markdown: {
    // Exemple : Traduire le texte des notes de bas de page dans une autre langue. Voici les valeurs anglaises par défaut.
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to reference 1"},
  },
};

i18n

Type : object

Ajouté à la version : astro@3.5.0

Configure le routage i18n et vous permet de spécifier certaines options de personnalisation.

Consultez notre guide pour plus d’informations sur l’internationalisation dans Astro

i18n.defaultLocale

Type : string

Ajouté à la version : astro@3.5.0

Les paramètres régionaux par défaut de votre site web/application. Ceci est un champ obligatoire.

Aucun format de langue ou syntaxe particulière n’est imposé, mais nous vous suggérons d’utiliser des minuscules et des traits d’union si nécessaire (par exemple « es », « pt-br ») pour une meilleure compatibilité.

i18n.locales

Type : Locales

Ajouté à la version : astro@3.5.0

Une liste de tous les paramètres régionaux pris en charge par le site Web, y compris defaultLocale. Ceci est un champ obligatoire.

Les langues peuvent être répertoriées soit sous forme de codes individuels (par exemple ['en', 'es', 'pt-br']) soit en associant un chemin (path) à un tableau de codes (par exemple { path: "english", codes: ["en", "en-US"]}). Ces codes seront utilisés pour déterminer la structure de l’URL de votre site déployé.

Aucun format particulier de code de langue ou de syntaxe n’est appliqué, mais les dossiers de votre projet contenant vos fichiers de contenu doivent correspondre exactement aux éléments de la liste locales. Dans le cas de plusieurs codes pointant vers un préfixe de chemin d’URL personnalisé, stockez vos fichiers de contenu dans un dossier portant le même nom que le chemin configuré (path).

i18n.fallback

Type : Record.<string, string>

Ajouté à la version : astro@3.5.0

La stratégie de repli lors de la navigation vers des pages qui n’existent pas (par exemple une page traduite n’a pas été créée).

Utilisez cet objet pour déclarer une route de repli pour chaque langue que vous prenez en charge. Si aucune solution de repli n’est spécifiée, les pages indisponibles renverront un code d’état 404.

Exemple

L’exemple suivant configure votre stratégie de repli pour rediriger les pages indisponibles dans /pt-br/ vers leur version es, et les pages indisponibles dans /fr/ vers leur version en. Les pages /es/ non disponibles renverront un code d’état 404.

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    fallback: {
      pt: "es",
      fr: "en"
    }
  }
})

i18n.routing

Type : Routing

Ajouté à la version : astro@3.7.0

Contrôle la stratégie de routage pour déterminer les URL de votre site. Définissez ceci en fonction de la configuration de votre chemin de dossier/URL pour votre langue par défaut.

i18n.routing.prefixDefaultLocale

Type : boolean
Par défaut : false

Ajouté à la version : astro@3.7.0

Lorsque le paramètre est défini sur false, seules les langues autres que celles par défaut afficheront un préfixe de langue. La langue par défaut (defaultLocale) n’affichera pas de préfixe de langue et les fichiers de contenu ne résident pas dans un dossier localisé. Les URL seront de la forme example.com/[locale]/content/ pour toutes les langues autres que celles par défaut, mais example.com/content/ pour la langue par défaut.

Lorsque le paramètre est défini sur true, toutes les URL afficheront un préfixe de langue. Les URL seront de la forme example.com/[locale]/content/ pour chaque route, y compris la langue par défaut. Les dossiers localisés sont utilisés pour chaque langue, y compris la langue par défaut.

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    routing: {
      prefixDefaultLocale: true,
    }
  }
})

i18n.routing.redirectToDefaultLocale

Type : boolean
Par défaut : true

Ajouté à la version : astro@4.2.0

Configure si l’URL d’accueil (/) générée par src/pages/index.astro sera redirigée vers /[defaultLocale] lorsque prefixDefaultLocale: true est défini.

Définissez redirectToDefaultLocale: false pour désactiver cette redirection automatique à la racine de votre site :

export default defineConfig({
  i18n:{
    defaultLocale: "en",
    locales: ["en", "fr"],
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: false
    }
  }
})

i18n.routing.manual

Type : string

Ajouté à la version : astro@4.6.0

Lorsque cette option est activée, Astro désactivera son middleware i18n afin que vous puissiez implémenter votre propre logique personnalisée. Aucune autre option de routage (routing) (par exemple prefixDefaultLocale) ne peut être configurée avec routing: "manual".

Vous serez responsable de l’écriture de votre propre logique de routage ou de l’exécution manuelle du middleware i18n d’Astro aux côtés du vôtre.

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    routing: {
      prefixDefaultLocale: true,
    }
  }
})

Indicateurs hérités

Pour aider certains utilisateurs à migrer entre les versions d’Astro, nous introduisons occasionnellement des indicateurs « hérités ». Ces indicateurs vous permettent d’activer certains comportements qui sont obsolètes ou dépassés dans la dernière version d’Astro, afin que vous puissiez continuer à les utiliser pendant que vous mettez à niveau votre projet et que vous puissiez profiter des nouvelles versions d’Astro.

Indicateurs expérimentaux

Astro propose des indicateurs expérimentaux pour donner aux utilisateurs un accès anticipé aux nouvelles fonctionnalités. La stabilité de ces indicateurs n’est pas garantie.

experimental.directRenderScript

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.5.0

Permet une stratégie plus fiable pour empêcher l’exécution de scripts dans des pages où ils ne sont pas utilisés.

Les scripts seront directement rendus tels que déclarés dans les fichiers Astro (y compris les fonctionnalités existantes telles que TypeScript, l’importation de node_modules et la déduplication des scripts). Vous pouvez également désormais restituer des scripts de manière conditionnelle dans votre fichier Astro. Cependant, cela signifie que les scripts ne sont plus remontés vers la balise <head> et que plusieurs scripts sur une page ne sont plus regroupés. Si vous activez cette option, vous devez vérifier que toutes vos balises <script> se comportent comme prévu.

Cette option sera activée par défaut dans Astro 5.0.

{
  experimental: {
    directRenderScript: true,
  },
}

experimental.actions

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.8.0

Les actions vous aident à écrire des fonctions backend avec des types sécurisés que vous pouvez appeler de n’importe où. Activez le rendu côté serveur en utilisant la propriété output et ajoutez l’indicateur actions à l’objet experimental :

{
  output: 'hybrid', // ou 'server'
  experimental: {
    actions: true,
  },
}

Déclarez toutes vos actions dans src/actions/index.ts. Ce fichier est le gestionnaire d’actions globales.

Définissez une action à l’aide de l’utilitaire defineAction() du module astro:actions. Une action accepte la propriété handler pour définir votre gestionnaire de requêtes côté serveur. Si votre action accepte des arguments, appliquez la propriété input pour valider les paramètres avec Zod.

Cet exemple définit deux actions : like et comment. L’action like accepte un objet JSON avec une chaîne de caractères postId, tandis que l’action comment accepte un objet FormData avec les propriétés postId, author et body. Chaque handler met à jour votre base de données et renvoie une réponse avec des types sécurisés.

import { defineAction, z } from "astro:actions";

export const server = {
  like: defineAction({
    input: z.object({ postId: z.string() }),
    handler: async ({ postId }) => {
      // mettre à jour les likes dans la base de données

      return likes;
    },
  }),
  comment: defineAction({
    accept: 'form',
    input: z.object({
      postId: z.string(),
      author: z.string(),
      body: z.string(),
    }),
    handler: async ({ postId }) => {
      // insérer des commentaires dans la base de données

      return comment;
    },
  }),
};

Ensuite, appelez une action à partir de vos composants clients en utilisant l’objet actions de astro:actions. Vous pouvez transmettre un objet avec des types sécurisés lors de l’utilisation de JSON ou un objet FormData lorsque vous utilisez accept: 'form' dans votre définition d’action.

Cet exemple appelle les actions like et comment à partir d’un composant React :

import { actions } from "astro:actions";
import { useState } from "react";

export function Like({ postId }: { postId: string }) {
  const [likes, setLikes] = useState(0);
  return (
    <button
      onClick={async () => {
        const newLikes = await actions.like({ postId });
        setLikes(newLikes);
      }}
    >
      {likes} likes
    </button>
  );
}

export function Comment({ postId }: { postId: string }) {
  return (
    <form
      onSubmit={async (e) => {
        e.preventDefault();
        const formData = new FormData(e.target as HTMLFormElement);
        const result = await actions.blog.comment(formData);
        // gérer le résultat
      }}
    >
      <input type="hidden" name="postId" value={postId} />
      <label htmlFor="author">Auteur</label>
      <input id="author" type="text" name="author" />
      <textarea rows={10} name="body"></textarea>
      <button type="submit">Envoyer</button>
    </form>
  );
}

Pour un aperçu complet et pour donner votre avis sur cette API expérimentale, consultez la RFC Actions.

experimental.contentCollectionCache

Type : boolean
Par défaut : false

Ajouté à la version : astro@3.5.0

Active un cache persistant pour les collections de contenu lors de la création en mode statique.

{
  experimental: {
    contentCollectionCache: true,
  },
}

experimental.contentCollectionJsonSchema

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.5.0

Cette fonctionnalité générera automatiquement un schéma JSON pour les collections de contenu de type données (type: 'data') qui peut être utilisé comme valeur $schema pour l’auto-complétion/les astuces de style TypeScript dans des outils comme VSCode.

Pour activer cette fonctionnalité, ajoutez l’indicateur expérimental :

import { defineConfig } from 'astro/config';
export default defineConfig({
  experimental: {
    contentCollectionJsonSchema: true
  }
});

Cette implémentation expérimentale nécessite de référencer manuellement le schéma dans chaque fichier de données de la collection :

{
  "$schema": "../../../.astro/collections/test.schema.json",
  "test": "test"
}

Alternativement, vous pouvez définir cela dans le paramètre json.schemas de votre configuration VSCode :

"json.schemas": [
  {
    "fileMatch": [
      "/src/content/test/**"
    ],
    "url": "./.astro/collections/test.schema.json"
  }
]

Notez que cette implémentation initiale utilise une bibliothèque avec des problèmes connus pour les schémas Zod avancés, vous souhaiterez peut-être consulter ces limitations avant d’activer l’indicateur expérimental.

experimental.clientPrerender

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.2.0

Permet le pré-rendu de vos pages préchargées sur le client dans les navigateurs pris en charge.

Cette fonctionnalité utilise l’API Web expérimentale des règles de spéculation et améliore globalement le comportement de prefetch par défaut pour pré-afficher les liens sur le client. Vous souhaiterez peut-être examiner les risques possibles lors du prérendu sur le client avant d’activer cette fonctionnalité.

Activez le prérendu côté client dans votre astro.config.mjs ainsi que toutes les options de configuration prefetch souhaitées :

{
  prefetch: {
    prefetchAll: true,
    defaultStrategy: 'viewport',
  },
  experimental: {
    clientPrerender: true,
  },
}

Continuez à utiliser l’attribut data-astro-prefetch sur n’importe quel lien <a /> sur votre site pour activer le préchargement. Au lieu d’ajouter une balise <link> à l’en-tête du document ou de récupérer la page avec JavaScript, une balise <script> sera ajoutée avec les règles de spéculation correspondantes.

Le prérendu côté client nécessite la prise en charge du navigateur. Si l’API des règles de spéculation n’est pas prise en charge, prefetch reviendra à la stratégie prise en charge.

Consultez le guide sur le préchargement pour découvrir plus d’options et d’utilisation de prefetch.

experimental.globalRoutePriority

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.2.0

Donne la priorité aux redirections et aux routes injectées de manière égale aux côtés des routes du projet basées sur les fichiers, en suivant les mêmes règles d’ordre de priorité des routes pour toutes les routes.

Cela permet plus de contrôle sur le routage dans votre projet en ne priorisant pas automatiquement certains types de routes et en standardisant l’ordre de priorité des routes pour toutes les routes.

L’exemple suivant montre quelle route créera certaines URL de page lorsque les routes basées sur des fichiers, les routes injectées et les redirections sont combinées comme indiqué ci-dessous :

Route basée sur les fichiers : /blog/post/[pid]
Route basée sur les fichiers : /[page]
Route injectée : /blog/[...slug]
Redirection : /blog/tags/[tag] -> /[tag]
Redirection : /posts -> /blog

Avec experimental.globalRoutingPriority activé (au lieu de l’ordre de priorité des routes par défaut d’Astro 4.0) :

/blog/tags/astro est construit par la redirection vers /tags/[tag] (au lieu de la route injectée /blog/[...slug])
/blog/post/0 est construit par la route basée sur les fichiers /blog/post/[pid] (au lieu de la route injectée /blog/[...slug])
/posts est construit par la redirection vers /blog (au lieu de la route basée sur les fichiers /[page])

En cas de collision de routes, où deux routes de priorité égale tentent de créer la même URL, Astro enregistrera un avertissement identifiant les routes en conflit.

experimental.rewriting

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.8.0

Active une fonctionnalité de routage pour la réécriture des requêtes dans les pages Astro, les points de terminaison et le middleware Astro, vous donnant un contrôle programmatique sur vos routes.

{
  experimental: {
    rewriting: true,
  },
}

Utilisez Astro.rewrite dans vos fichiers .astro pour rediriger vers une autre page :

---
if (!Astro.props.allowed) {
  return Astro.rewrite("/")
}
---

Utilisez context.rewrite dans vos fichiers de point de terminaison pour rediriger vers une autre page :

export function GET(ctx) {
  if (!ctx.locals.allowed) {
    return ctx.rewrite("/")
  }
}

Utilisez next("/") dans votre fichier middleware pour rediriger vers une autre page, puis appelez la fonction middleware suivante :

export function onRequest(ctx, next) {
  if (!ctx.cookies.get("allowed")) {
    return next("/") // nouvelle signature
  }
  return next();
}

Pour un aperçu complet et pour donner votre avis sur cette API expérimentale, consultez la RFC Rerouting.

experimental.env

Type : object
Par défaut : undefined

Ajouté à la version : astro@4.10.0

Active les fonctionnalités expérimentales astro:env.

L’API astro:env vous permet de configurer un schéma de type sécurisé pour vos variables d’environnement et d’indiquer si elles doivent être disponibles sur le serveur ou sur le client. Importez et utilisez vos variables définies à partir du module approprié /client ou /server :

---
import { APP_ID } from "astro:env/client"
import { API_URL, API_TOKEN, getSecret } from "astro:env/server"
const NODE_ENV = getSecret("NODE_ENV")

const data = await fetch(`${API_URL}/users`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_TOKEN}`
  },
  body: JSON.stringify({ appId: APP_ID, nodeEnv: NODE_ENV })
})
---

Pour définir le type de données et les propriétés de vos variables d’environnement, déclarez un schéma dans votre configuration Astro dans experimental.env.schema. L’assistant envField vous permet de définir votre variable sous forme de chaîne de caractères, de nombre ou de booléen et de transmettre des propriétés dans un objet :

import { defineConfig, envField } from "astro/config"

export default defineConfig({
    experimental: {
        env: {
            schema: {
                API_URL: envField.string({ context: "client", access: "public", optional: true }),
                PORT: envField.number({ context: "server", access: "public", default: 4321 }),
                API_SECRET: envField.string({ context: "server", access: "secret" }),
            }
        }
    }
})

Il existe actuellement quatre types de données pris en charge : chaînes de caractères, nombres, booléens et énumérations.

Il existe trois types de variables d’environnement, déterminées par la combinaison des paramètres context (client ou server) et access (secret ou public) définis dans la propriété env.schema :

Variables du client public : Ces variables se retrouvent à la fois dans vos bundles client et serveur finaux, et sont accessibles à la fois depuis le client et le serveur via le module astro:env/client :
```
import { API_URL } from "astro:env/client"
```
Variables du serveur public : Ces variables se retrouvent dans votre bundle de serveur final et sont accessibles sur le serveur via le module astro:env/server :
```
import { PORT } from "astro:env/server"
```
Variables secrètes du serveur : Ces variables ne font pas partie de votre bundle final et sont accessibles sur le serveur via le module astro:env/server. La fonction d’assistance getSecret() peut être utilisée pour récupérer des secrets non spécifiés dans le schéma :
```
import { API_SECRET, getSecret } from "astro:env/server"

const SECRET_NOT_IN_SCHEMA = getSecret("SECRET_NOT_IN_SCHEMA") // string | undefined
```

Remarque : Les variables secrètes du client ne sont pas prises en charge car il n’existe aucun moyen sûr d’envoyer ces données au client. Par conséquent, il n’est pas possible de configurer à la fois context: "client" et access: "secret" dans votre schéma.

Pour un aperçu complet et pour donner votre avis sur cette API expérimentale, voir la RFC d’Astro Env.

experimental.env.schema

Type : EnvSchema
Par défaut : undefined

Ajouté à la version : astro@4.10.0

Un objet qui utilise envField pour définir le type de données (string, number ou boolean) et les propriétés de vos variables d’environnement : context (client ou serveur), access (public ou secret) , une valeur par défaut (default) à utiliser et si cette variable d’environnement est facultative (optional) ou non (la valeur par défaut est false).

import { defineConfig, envField } from "astro/config"

export default defineConfig({
  experimental: {
    env: {
      schema: {
        API_URL: envField.string({ context: "client", access: "public", optional: true }),
        PORT: envField.number({ context: "server", access: "public", default: 4321 }),
        API_SECRET: envField.string({ context: "server", access: "secret" }),
      }
    }
  }
})

experimental.env.validateSecrets

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.11.6

Détermine s’il faut ou non valider les secrets sur le serveur lors du démarrage du serveur de développement ou de l’exécution d’une construction.

Par défaut, seules les variables publiques sont validées sur le serveur lors du démarrage du serveur de développement ou d’une construction, et les variables privées sont validées uniquement au moment de l’exécution. Si elles sont activées, les variables privées seront également vérifiées au démarrage. Ceci est utile dans certains pipelines d’intégration continue (CI) pour vous assurer que tous vos secrets sont correctement définis avant le déploiement.

import { defineConfig, envField } from "astro/config"

export default defineConfig({
  experimental: {
    env: {
      schema: {
        // ...
      },
      validateSecrets: true
    }
  }
})

experimental.serverIslands

Type : boolean
Par défaut : false

Ajouté à la version : astro@4.12.0 Nouveau

Active les fonctionnalités expérimentales des Îles de serveurs. Les Îles de serveurs offrent la possibilité de différer le rendu asynchrone d’un composant une fois le rendu de la page terminé.

Pour l’activer, définissez un mode de sortie (output) permettant le rendu à la demande côté serveur avec un adaptateur, et ajoutez le drapeau serverIslands à l’objet experimental :

{
  output: 'hybrid', // ou 'server'
  adapter: nodejs({ mode: 'standalone' }),
  experimental: {
    serverIslands: true,
  },
}

Utilisez la directive server:defer sur n’importe quel composant Astro pour retarder le rendu initial :

---
import Avatar from '~/components/Avatar.astro';
---
<Avatar server:defer />

La page externe sera rendue, soit au moment de la construction (hybrid) ou au moment de l’exécution (server) avec le contenu de l’île omis et une balise <script> incluse à sa place.

Une fois la page chargée dans le navigateur, la balise de script se remplacera par le contenu de l’île en faisant une requête.

Tout composant Astro peut recevoir l’attribut server: defer pour retarder son rendu. Il n’y a pas d’API spéciale et vous pouvez écrire du code .astro comme d’habitude :

---
import { getUser } from '../api';

const user = await getUser(Astro.locals.userId);
---
<img class="avatar" src={user.imageUrl}>

Contenu de secours des Îles de serveurs

Étant donné que votre composant ne s’affichera pas avec le reste de la page, vous souhaiterez peut-être ajouter du contenu générique (par exemple un message de chargement) à afficher temporairement à sa place. Ce contenu sera affiché lors du premier rendu de la page, mais avant le chargement de l’île.

Ajoutez du contenu d’espace réservé en tant qu’enfant de votre composant Astro avec l’attribut slot="fallback". Lorsque le contenu de votre île est disponible, le contenu de secours sera remplacé.

L’exemple ci-dessous affiche un avatar générique comme contenu de secours, puis s’anime en un avatar personnalisé à l’aide de transitions de vue :

<Avatar server:defer>
  <svg slot="fallback" class="generic-avatar" transition:name="avatar">...</svg>
</Avatar>

Pour un aperçu complet et pour donner votre avis sur cette API expérimentale, voir la RFC des Îles de serveurs.

Contribuer

Communauté