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 : object
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 vite.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',
  },
}

build.concurrency

Type : number
Par défault : 1

Ajouté à la version : astro@4.16.0 Nouveau

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.

{
  build: {
    concurrency: 2
  }
}

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 : []

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>

Shiki est notre colorateur syntaxique par défaut. Vous pouvez configurer toutes les options via l’objet markdown.shikiConfig :

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      // Choisir parmi les thèmes intégrés de Shiki (ou ajouter le vôtre)
      // https://shiki.style/themes
      theme: 'dracula',
      // Alternativement, proposer plusieurs thèmes
      // Voir la note ci-dessous pour utiliser les thèmes doubles clair/sombre
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // Désactiver les couleurs par défaut
      // https://shiki.style/guide/dual-themes#without-default-color
      // (Ajouté dans la v4.12.0)
      defaultColor: false,
      // Ajouter des langages personnalisés
      // Remarque : Shiki possède d’innombrables langages intégrés, y compris .astro !
      // https://shiki.style/languages
      langs: [],
      // Ajouter des alias personnalisés pour les langages
      // Associer un alias à un identifiant de langage Shiki : https://shiki.style/languages#bundled-languages
      // https://shiki.style/guide/load-lang#custom-language-aliases
      langAlias: {
        cjs: "javascript"
      },
      // Activer le retour à la ligne pour empêcher le défilement horizontal
      wrap: true,
      // Ajouter des transformateurs personnalisés : https://shiki.style/guide/transformers
      // Trouver des transformateurs courants : https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});

Consultez le guide de coloration syntaxique du code pour l’utilisation et les exemples.

markdown.syntaxHighlight

Type : '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ème github-dark configuré par défaut)
prism - utiliser le colorateur Prism et fournir votre propre feuille de style Prism
false - n’appliquer 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.fallbackType

Type : "redirect" | "rewrite"
Par défaut : "redirect"

Ajouté à la version : 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é.

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

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.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.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.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 { API_URL } from "astro:env/client"
import { API_SECRET_TOKEN } from "astro:env/server"

const data = await fetch(`${API_URL}/users`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_SECRET_TOKEN}`
  },
})
---

<script>
import { API_URL } from "astro:env/client"

fetch(`${API_URL}/ping`)
</script>

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. Son implémentation est fournie par votre adaptateur et utilisera process.env par défaut :
```
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

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.

experimental.contentIntellisense

Type : boolean
Par défaut : false

Ajouté à la version : 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).

{
  experimental: {
    contentIntellisense: true,
  },
}

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

Type : boolean
Par défaut : false

Ajouté à la version : 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 :

{
  experimental: {
    contentLayer: true,
  }
}

Récupérer des données avec un `loader`

L’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.

import { defineCollection, z } from 'astro:content';
import { glob, file } from 'astro/loaders';

const blog = defineCollection({
  // Par défaut, l'ID est un slug généré à partir de
  // du chemin du fichier par rapport à `base`
  loader: glob({ pattern: "**\/*.md", base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  })
});

const dogs = defineCollection({
  // Le chemin est relatif à la racine du projet ou un chemin absolu.
  loader: file("src/data/dogs.json"),
  schema: z.object({
    id: z.string(),
    breed: z.string(),
    temperament: z.array(z.string()),
  }),
});

export const collections = { blog, dogs };

Interrogation et rendu avec l’API Content Layer

La collection peut être interrogée de la même manière que les collections de contenu:

import { getCollection, getEntry } from 'astro:content';

// Obtenir toutes les entrées d'une collection.
// Nécessite le nom de la collection comme argument.
const allBlogPosts = await getCollection('blog');

// Obtenir une seule entrée d’une collection.
// Nécessite le nom de la collection et l'ID
const labradorData = await getEntry('dogs', 'labrador-retriever');

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

---
import { getEntry, render } from 'astro:content';

const post = await getEntry('blog', Astro.params.slug);

const { Content, headings } = await render(post);
---

<Content />

Créer un chargeur

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

const countries = defineCollection({
  loader: async () => {
    const response = await fetch("https://restcountries.com/v3.1/all");
    const data = await response.json();
    // Doit renvoyer un tableau d'entrées avec une propriété id
    // ou un objet avec des ID comme clés et des entrées comme valeurs
    return data.map((country) => ({
      id: country.cca3,
      ...country,
    }));
  },
  // ajouter éventuellement un schéma
  // schema: z.object...
});

export const collections = { countries };

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

Vous 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 vers src/data/). Toutes les collections situées dans le dossier src/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 un type de collection n’est plus disponible.

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  // Pour la couche de contenu, vous ne définissez plus de `type`
  type: 'content',
  loader: glob({ pattern: "**\/*.md", base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});

Changez les références de slug à id. Les collections de la couche de contenu n’ont pas de champ slug. À la place, toutes les collections mises à jour auront un champ id.

---
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.slug },
    params: { slug: post.id },
    props: post,
  }));
}
---

Basculez vers la nouvelle fonction render(). Les entrées n’ont plus de méthode render(), car elles sont désormais des objets simples sérialisables. Au lieu de cela, importez la fonction render() depuis astro:content.

---
import { getEntry } from 'astro:content';
import { getEntry, render } from 'astro:content';

const post = await getEntry('blog', params.slug);

const { Content, headings } = await post.render();
const { Content, headings } = await render(post);
---

<Content />

En savoir plus

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

Contribuer

Communauté

Sponsorisé par

Sponsorisé par

Sponsorisé par

Sponsorisé par

Sponsorisé par

Référence de configuration

Options de niveau supérieur

site

base

trailingSlash

redirects

output

adapter

integrations

root

Exemples

srcDir

publicDir

outDir

cacheDir

compressHTML

scopedStyleStrategy

security

security.checkOrigin

vite

Exemples

Options de construction

build.format

Effet sur Astro.url

build.client

build.server

build.assets

build.assetsPrefix

build.serverEntry

build.redirects

build.inlineStylesheets

build.concurrency

Options du serveur

server.host

server.port

server.open

server.headers

Options de la barre d’outils de développement

devToolbar.enabled

Options de préchargement

prefetch.prefetchAll

prefetch.defaultStrategy

Options d’images

image.endpoint

image.service

image.service.config.limitInputPixels

image.domains

image.remotePatterns

Options de Markdown

markdown.shikiConfig

markdown.syntaxHighlight

markdown.remarkPlugins

markdown.rehypePlugins

markdown.gfm

markdown.smartypants

markdown.remarkRehype

i18n

i18n.defaultLocale

i18n.locales

i18n.fallback

Exemple

i18n.routing

i18n.routing.prefixDefaultLocale

i18n.routing.redirectToDefaultLocale

i18n.routing.fallbackType

i18n.routing.manual

Indicateurs hérités

Indicateurs expérimentaux

experimental.directRenderScript

experimental.contentCollectionCache

experimental.clientPrerender

experimental.globalRoutePriority

experimental.env

experimental.env.schema

experimental.env.validateSecrets

Récupérer des données avec un `loader`