Référence de configuration
La référence suivante couvre toutes les options de configuration prises en charge dans Astro.
Options de niveau supérieur
Titre de la section Options de niveau supérieurType : 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.
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
.
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
:
Dans l’exemple ci-dessous, les valeurs de import.meta.env.BASE_URL
et config.base
une fois traitées seront toutes deux /docs/
:
trailingSlash
Titre de la section trailingSlashType : '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.
Voir aussi :
- build.format
redirects
Titre de la section redirectsType : Record.<string, RedirectConfig>
Par défaut : {}
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]'
.
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 :
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.
Voir aussi :
- adapter
adapter
Titre de la section adapterType : 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 (EN) pour en savoir plus sur SSR et nos guides de déploiement pour une liste complète des hôtes.
Voir aussi :
- output
integrations
Titre de la section integrationsType : 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.
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
Titre de la section ExemplesType : 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.
publicDir
Titre de la section publicDirType : 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.
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.
Voir aussi :
- build.server
cacheDir
Titre de la section cacheDirType : 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.
compressHTML
Titre de la section compressHTMLType : 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.
scopedStyleStrategy
Titre de la section scopedStyleStrategyType : 'where' | 'class' | 'attribute'
Par défaut : 'attribute'
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 attributsdata-
, 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
Titre de la section securityType : object
Par défaut : {}
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
).
security.checkOrigin
Titre de la section security.checkOriginType : boolean
Par défaut : false
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.
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 vite.dev.
Exemples
Titre de la section ExemplesOptions de construction
Titre de la section Options de constructionbuild.format
Titre de la section build.formatType : ('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
etsrc/pages/about/index.astro
construisent tous deux le fichier/about.html
)'directory'
: Astro générera un répertoire avec un fichierindex.html
imbriqué pour chaque page. (par exemple,src/pages/about.astro
etsrc/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
etsrc/pages/about/index.astro
construit le fichier/about/index.html
)
Effet sur Astro.url
Titre de la section Effet sur Astro.urlLa 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éfinisseztrailingSlash: 'always'
file
- DéfinisseztrailingSlash: 'never'
build.client
Titre de la section build.clientType : 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
.
build.server
Titre de la section build.serverType : 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.assets
Titre de la section build.assetsType : string
Par défaut : '_astro'
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).
Voir aussi :
- outDir
build.assetsPrefix
Titre de la section build.assetsPrefixType : string | Record.<string, string>
Par défaut : undefined
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
) :
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.serverEntry
Titre de la section build.serverEntryType : 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.redirects
Titre de la section build.redirectsType : boolean
Par défaut : true
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.inlineStylesheets
Titre de la section build.inlineStylesheetsType : 'always' | 'auto' | 'never'
Par défaut : auto
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 deViteConfig.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.concurrency
Titre de la section build.concurrencyType : number
Par défault : 1
astro@4.16.0
Le nombre de pages à construire en parallèle.
Dans la plupart des cas, vous ne devriez pas modifier la valeur par défaut de 1
.
Utilisez cette option uniquement lorsque d’autres tentatives visant à réduire le temps de rendu global (par exemple, des tâches de longue durée mises par lots ou en cache comme des appels de récupération ou l’accès à des données) ne sont pas possibles ou sont insuffisantes. Si le nombre est trop élevé, le rendu de la page peut ralentir en raison de ressources mémoire insuffisantes et parce que JS est monothread.
Cette fonctionnalité est stable et n’est pas considérée comme expérimentale. Cependant, celle-ci est uniquement destinée à résoudre des problèmes de performances difficiles, et des modifications importantes peuvent survenir dans une version mineure pour maintenir cette option aussi performante que possible. Veuillez vérifier le CHANGELOG d’Astro pour chaque version mineure si vous utilisez cette fonctionnalité.
Options du serveur
Titre de la section Options du serveurPersonnalise le serveur de développement Astro, utilisé à la fois par astro dev
et astro preview
.
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.
server.host
Titre de la section server.hostType : string | boolean
Par défaut : false
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éseautrue
- é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
Titre de la section server.portType : 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.open
Titre de la section server.openType : string | boolean
Par défaut : false
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.headers
Titre de la section server.headersType : OutgoingHttpHeaders
Par défaut : {}
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
Titre de la section Options de la barre d’outils de développementdevToolbar.enabled
Titre de la section devToolbar.enabledType : 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
Titre de la section Options de préchargementType : 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.
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
Titre de la section prefetch.prefetchAllType : 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
.
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.
prefetch.defaultStrategy
Titre de la section prefetch.defaultStrategyType : '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.
Options d’images
Titre de la section Options d’imagesimage.endpoint
Titre de la section image.endpointType : string
Par défaut : undefined
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.service
Titre de la section image.serviceType : Object
Par défaut : {entrypoint: 'astro/assets/services/sharp', config?: {}}
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.service.config.limitInputPixels
Titre de la section image.service.config.limitInputPixelsType : number | boolean
Par défaut : true
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
Titre de la section image.domainsType : Array.<string>
Par défaut : []
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.remotePatterns
Titre de la section image.remotePatternsType : Array.<RemotePattern>
Par défaut : {remotePatterns: []}
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
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
Titre de la section Options de Markdownmarkdown.shikiConfig
Titre de la section markdown.shikiConfigType : Partial<ShikiConfig>
Shiki est notre colorateur syntaxique par défaut. Vous pouvez configurer toutes les options via l’objet markdown.shikiConfig
:
Consultez le guide de coloration syntaxique du code pour l’utilisation et les exemples.
markdown.syntaxHighlight
Titre de la section markdown.syntaxHighlightType : 'shiki' | 'prism' | false
Par défaut : shiki
Quel surligneur de syntaxe utiliser pour les blocs de code Markdown (```), le cas échéant. Cela détermine les classes CSS qu’Astro appliquera à vos blocs de code Markdown.
shiki
- utiliser le colorateur Shiki (thèmegithub-dark
configuré par défaut)prism
- utiliser le colorateur Prism et fournir votre propre feuille de style Prismfalse
- n’appliquer aucune coloration syntaxique.
markdown.remarkPlugins
Titre de la section markdown.remarkPluginsType : 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.
markdown.rehypePlugins
Titre de la section markdown.rehypePluginsType : 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.
markdown.gfm
Titre de la section markdown.gfmType : boolean
Par défaut : true
astro@2.0.0
Astro utilise GitHub-flavored Markdown par défaut. Pour désactiver cela, définissez l’indicateur gfm
sur false
:
markdown.smartypants
Titre de la section markdown.smartypantsType : boolean
Par défaut : true
astro@2.0.0
Astro utilise le formatteur SmartyPants par défaut. Pour désactiver cela, définissez l’indicateur smartypants
sur false
:
markdown.remarkRehype
Titre de la section markdown.remarkRehypeType : RemarkRehype
Transmet des options à remark-rehype.
Type : object
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
Titre de la section i18n.defaultLocaleType : string
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
Titre de la section i18n.localesType : Locales
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
Titre de la section i18n.fallbackType : Record.<string, string>
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
Titre de la section ExempleL’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.
i18n.routing
Titre de la section i18n.routingType : Routing
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
Titre de la section i18n.routing.prefixDefaultLocaleType : boolean
Par défaut : false
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.
i18n.routing.redirectToDefaultLocale
Titre de la section i18n.routing.redirectToDefaultLocaleType : boolean
Par défaut : true
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 :
i18n.routing.fallbackType
Titre de la section i18n.routing.fallbackTypeType : "redirect" | "rewrite"
Par défaut : "redirect"
astro@4.15.0
Lorsque i18n.fallback
est configuré pour éviter d’afficher une page 404 pour les routes de page manquantes, cette option contrôle s’il faut rediriger vers la page de secours ou réécrire le contenu de la page de secours en place.
Par défaut, le routage i18n d’Astro crée des pages qui redirigent vos visiteurs vers une nouvelle destination en fonction de votre configuration de secours. Le navigateur s’actualise et affiche l’adresse de destination dans la barre d’URL.
Lorsque i18n.routing.fallback: "rewrite"
est configuré, Astro crée des pages qui restituent le contenu de la page de secours sur l’URL d’origine demandée.
Avec la configuration suivante, si vous avez le fichier src/pages/en/about.astro
mais pas src/pages/fr/about.astro
, la commande astro build
générera dist/fr/about.html
avec le même contenu que la page dist/en/about.html
.
Le visiteur de votre site verra la version anglaise de la page à l’adresse https://example.com/fr/about/
et ne sera pas redirigé.
i18n.routing.manual
Titre de la section i18n.routing.manualType : string
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.
Indicateurs hérités
Titre de la section Indicateurs héritésPour 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
Titre de la section Indicateurs expérimentauxAstro 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
Titre de la section experimental.directRenderScriptType : boolean
Par défaut : false
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.contentCollectionCache
Titre de la section experimental.contentCollectionCacheType : boolean
Par défaut : false
astro@3.5.0
Active un cache persistant pour les collections de contenu lors de la création en mode statique.
experimental.clientPrerender
Titre de la section experimental.clientPrerenderType : boolean
Par défaut : false
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 :
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
Titre de la section experimental.globalRoutePriorityType : boolean
Par défaut : false
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.env
Titre de la section experimental.envType : object
Par défaut : undefined
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
:
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 :
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
: -
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
: -
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’assistancegetSecret()
peut être utilisée pour récupérer des secrets non spécifiés dans le schéma. Son implémentation est fournie par votre adaptateur et utiliseraprocess.env
par défaut :
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
Titre de la section experimental.env.schemaType : EnvSchema
Par défaut : undefined
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
).
experimental.env.validateSecrets
Titre de la section experimental.env.validateSecretsType : boolean
Par défaut : false
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.
experimental.serverIslands
Titre de la section experimental.serverIslandsType : boolean
Par défaut : false
astro@4.12.0
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 (EN) avec un adaptateur, et ajoutez le drapeau serverIslands
à l’objet experimental
:
Utilisez la directive server:defer
sur n’importe quel composant Astro pour retarder le rendu initial :
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 :
Contenu de secours des Îles de serveurs
Titre de la section 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 :
Pour un aperçu complet et pour donner votre avis sur cette API expérimentale, voir la RFC des Îles de serveurs.
experimental.contentIntellisense
Titre de la section experimental.contentIntellisenseType : boolean
Par défaut : false
astro@4.14.0
Active les fonctionnalités Intellisense (par exemple, la saisie semi-automatique du code, les astuces rapides) pour vos entrées de collection de contenu dans les éditeurs compatibles.
Lorsqu’elle est activée, cette fonctionnalité génère et ajoute des schémas JSON au répertoire .astro
de votre projet. Ces fichiers peuvent être utilisés par le serveur de langage Astro pour fournir les fonctionnalités Intellisense dans les fichiers de contenu (.md
, .mdx
, .mdoc
).
Pour utiliser cette fonctionnalité avec l’extension Astro de VS Code, vous devez également activer l’option astro.content-intellisense
dans vos paramètres VS Code. Pour les éditeurs utilisant directement le serveur de langage Astro, transmettez le paramètre d’initialisation contentIntellisense: true
pour activer cette fonctionnalité. Consultez la PR d’implémentation de Content Intellisense pour plus de détails sur cette fonctionnalité précoce.
experimental.contentLayer
Titre de la section experimental.contentLayerType : boolean
Par défaut : false
astro@4.14.0
L’API Content Layer est une nouvelle façon de gérer le contenu et les données dans Astro. Elle est similaire aux collections de contenu et s’appuie sur celles-ci. Elle les emmène au-delà des fichiers locaux dans src/content/
et vous permet de récupérer du contenu depuis n’importe quel emplacement, y compris des API distantes, en ajoutant un loader
à votre collection.
Vos collections de contenu existantes peuvent être migrées vers l’API Content Layer avec quelques petites modifications. Cependant, il n’est pas nécessaire de mettre à jour toutes vos collections en même temps pour ajouter une nouvelle collection alimentée par l’API Content Layer. Vous pouvez avoir des collections utilisant en même temps les API existantes et les nouvelles API définies dans src/content/config.ts
.
L’API Content Layer est conçue pour être plus puissante et plus performante, aidant les sites à évoluer vers des milliers de pages. Les données sont mises en cache entre les builds et mises à jour de manière incrémentielle. L’analyse Markdown est également 5 à 10 fois plus rapide, avec des réductions d’échelle similaires en mémoire, et MDX est 2 à 3 fois plus rapide.
Pour l’activer, ajoutez l’indicateur contentLayer
dans l’objet experimental
de votre configuration Astro :
Récupérer des données avec un loader
Titre de la section Récupérer des données avec un loaderL’API Content Layer vous permet de récupérer votre contenu en dehors du dossier src/content/
(qu’il soit stocké localement dans votre projet ou à distance) et utilise une propriété loader
pour récupérer vos données.
Le chargeur (loader
) est défini dans le schéma de la collection et renvoie un tableau d’entrées. Astro fournit deux fonctions de chargement intégrées (glob()
et file()
) pour récupérer votre contenu local, ainsi qu’un accès à l’API pour construire votre propre chargeur et récupérer des données distantes.
Le chargeur glob()
crée des entrées à partir de répertoires de fichiers Markdown, MDX, Markdoc ou JSON depuis n’importe quel endroit du système de fichiers. Il accepte un modèle de fichiers d’entrée (pattern
) à faire correspondre et un chemin de base (base
) indiquant où se trouvent vos fichiers. Utilisez ceci lorsque vous avez un fichier par entrée.
Le chargeur file()
crée plusieurs entrées à partir d’un seul fichier local. Utilisez-le lorsque toutes vos entrées sont stockées dans un tableau d’objets.
Les chargeurs n’excluront pas automatiquement les fichiers précédés d’un _
. Utilisez une expression régulière telle que pattern: '**\/[^_]*.md'
dans votre chargeur pour ignorer ces fichiers.
Interrogation et rendu avec l’API Content Layer
Titre de la section Interrogation et rendu avec l’API Content LayerLa collection peut être interrogée de la même manière que les collections de contenu:
Les entrées générées à partir de Markdown, MDX ou Markdoc peuvent être restituées directement sur une page à l’aide de la fonction render()
.
La syntaxe de rendu des entrées de collection est différente de la syntaxe actuelle des collections de contenu.
Créer un chargeur
Titre de la section Créer un chargeurAvec l’API Content Layer, vous pouvez créer des chargeurs pour charger ou générer du contenu depuis n’importe quel emplacement.
Par exemple, vous pouvez créer un chargeur qui récupère les entrées de collection à partir d’une API distante.
Pour une logique de chargement plus avancée, vous pouvez définir un chargeur d’objets. Cela permet des mises à jour incrémentielles et un chargement conditionnel tout en offrant un accès complet au magasin de données. Consultez l’API dans la RFC de l’API Content Layer.
Migration d’une collection de contenu existante pour utiliser l’API Content Layer
Titre de la section Migration d’une collection de contenu existante pour utiliser l’API Content LayerVous pouvez convertir une collection de contenu existante avec des entrées Markdown, MDX, Markdoc ou JSON pour utiliser l’API Content Layer.
-
Déplacez le dossier de collection hors de
src/content/
(par exemple verssrc/data/
). Toutes les collections situées dans le dossiersrc/content/
utiliseront l’API existante des collections de contenu.Ne déplacez pas le fichier existant
src/content/config.ts
. Ce fichier définira toutes les collections, en utilisant l’une ou l’autre API. -
Modifiez la définition de la collection. Votre collection mise à jour nécessite un chargeur (
loader
) et l’option permettant de sélectionner untype
de collection n’est plus disponible. -
Changez les références de
slug
àid
. Les collections de la couche de contenu n’ont pas de champslug
. À la place, toutes les collections mises à jour auront un champid
. -
Basculez vers la nouvelle fonction
render()
. Les entrées n’ont plus de méthoderender()
, car elles sont désormais des objets simples sérialisables. Au lieu de cela, importez la fonctionrender()
depuisastro:content
.
En savoir plus
Titre de la section En savoir plusPour retrouver une présentation complète et la référence détaillée de l’API, consultez le RFC de l’API de la couche de contenu et partagez vos commentaires.
Reference