API des chargeurs de contenu d'Astro

L’API des chargeurs de contenu d’Astro (Content Loader) vous permet de charger vos données à partir de n’importe quelle source, locale ou distante, et d’interagir avec la couche de contenu d’Astro pour gérer vos collections de contenu.

Cette API inclut deux chargeurs prêts à l’emploi pour le contenu stocké localement. Elle fournit également des outils permettant de créer vos propres objets personnalisés capables de charger des données depuis n’importe quelle source dans des collections de contenu.

Apprenez-en davantage sur l’interrogation des données chargées au moment de la compilation à l’aide de chargeurs ou l’accès aux données en direct à partir des chargeurs en direct grâce à des explications guidées et des exemples d’utilisation dans le guide des collections de contenu.

Chargeurs appelés lors de la compilation

Les chargeurs utilisés lors de la compilation sont des objets dotés d’une méthode load() appelée au moment de la compilation pour récupérer les données et mettre à jour le magasin de données. Cet objet peut également définir un schéma pour les entrées, qui peut être utilisé pour valider les données et générer des types statiques.

Les chargeurs glob() et file() d’Astro sont des exemples de chargeurs sous forme d’objet fournis et prêts à l’emploi pour une utilisation avec du contenu local. Pour le contenu distant, aucun chargeur prédéfini n’est fourni. Vous devrez créer un chargeur sous forme d’objet ou utiliser un chargeur publié par la communauté pour récupérer le contenu distant et interagir avec le magasin de données.

Pour une simple récupération de données, vous pouvez également définir un chargeur en tant qu’une fonction asynchrone qui renvoie un tableau ou un objet contenant des entrées.

Le chargeur glob()

Type : (options: GlobOptions) => Loader

Ajouté à la version : astro@5.0.0

Le chargeur glob() crée des entrées à partir de répertoires de fichiers situés n’importe où sur le système de fichiers. Les types de fichiers pris en charge sont les fichiers Markdown, MDX, Markdoc, JSON, YAML et TOML.

Ce chargeur accepte un objet avec les propriétés suivantes : pattern, base (optionnel), generateId (optionnel) et retainBody (optionnel).

src/content.config.ts

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

const pages = defineCollection({
  /* Récupère tous les fichiers Markdown dans votre répertoire de pages. */
  loader: glob({ pattern: "**/*.md", base: "./src/data/pages" }),
});
const blog = defineCollection({
  /* Récupère tous les fichiers Markdown et MDX dans le répertoire de votre blog. */
  loader: glob({ pattern: "**/*.(md|mdx)", base: "./src/data/blog" }),
});
const notes = defineCollection({
  /* Récupére tous les fichiers Markdown de votre répertoire de notes et empêche
   * le stockage du contenu brut de ces fichiers dans le magasin de données. */
  loader: glob({
    pattern: '**/*.md',
    base: './src/data/notes',
    retainBody: false
  }),
});
const authors = defineCollection({
  /* Récupère tous les fichiers JSON dans votre
  * répertoire d'auteurs en conservant les lettres majuscules dans l'ID. */
  loader: glob({
    pattern: '**/*.json',
    base: "./src/data/auteurs",
    generateId: ({ entry }) => entry.replace(/\.json$/, ''),
  }),
});

export const collections = { pages, blog, authors };

pattern

Type : string | string[]

La propriété pattern accepte une chaîne de caractères ou un tableau de chaînes de caractères utilisant une correspondance glob (par exemple, des caractères génériques ou des caractères d’expansion glob). Les motifs doivent être relatifs au répertoire de base des fichiers d’entrée à comparer.

Pour en savoir plus sur la syntaxe à utiliser, consultez la documentation de micromatch. Vous pouvez également vérifier la validité de votre motif à l’aide d’un outil en ligne tel que l’outil Glob de DigitalOcean.

base

Type : string | URL
Par défaut : "."

Un chemin relatif ou une URL vers le répertoire à partir duquel résoudre le pattern.

generateId()

Type : (options: GenerateIdOptions) => string

Une fonction de rappel qui renvoie une chaîne de caractères unique pour chaque entrée d’une collection. Elle accepte un objet comme paramètre avec les propriétés suivantes :

• entry - le chemin d’accès au fichier d’entrée, par rapport au répertoire de base
• base - l’URL du répertoire de base
• data - les données analysées et non validées de l’entrée

Par défaut, elle utilise github-slugger pour générer un slug avec des mots au format kebab-case.

retainBody

Type : boolean
Par défaut : true

Ajouté à la version : astro@5.17.0

Détermine s’il faut ou non stocker le contenu brut des fichiers dans le magasin de données.

Lorsque retainBody est défini sur false, entry.body sera undefined au lieu de contenir le contenu brut du fichier.

Définir cette propriété sur false réduit considérablement la taille déployée du magasin de données et permet d’éviter d’atteindre les limites de taille pour les sites comportant de très grandes collections.

Pour les fichiers Markdown, le contenu rendu sera toujours disponible dans la propriété entry.rendered.html, et la propriété entry.filePath pointera toujours vers le fichier d’origine.

Pour les collections MDX, cela réduira considérablement leur taille, puisqu’aucun contenu ne sera plus conservé en magasin.

Le chargeur file()

Type : (fileName: string, options?: FileOptions) => Loader

Ajouté à la version : astro@5.0.0

Le chargeur file() crée des entrées à partir d’un seul fichier contenant un tableau d’objets avec un champ id unique, ou un objet avec des identifiants comme noms de propriété et des entrées comme valeurs.

Il prend en charge les fichiers JSON, YAML ou TOML et vous pouvez fournir une fonction d’analyse (parser) personnalisée pour les fichiers de données qu’il ne peut pas analyser par défaut, ou pour analyser les données de manière asynchrone.

Ce chargeur accepte une propriété fileName et un objet optionnel comme second argument :

src/content.config.ts

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

const authors = defineCollection({
  /* Récupère toutes les entrées d'un fichier JSON. */
  loader: file("src/data/auteurs.json"),
});
const products = defineCollection({
  /* Récupère toutes les entrées d'un fichier CSV à l'aide d'un analyseur personnalisé. */
  loader: file("src/data/produits.csv", {
    parser: (fileContent) => { /* la logique de votre analyseur */ },
  }),
});

export const collections = { authors, products };

fileName

Type : string

Définit le chemin d’accès au fichier à charger, par rapport au répertoire racine.

Options

Type : FileOptions

Un objet optionnel avec les propriétés suivantes :

parser()

Type : (text: string) => Record<string, Record<string, unknown>> | Array<Record<string, unknown>> | Promise<Record<string, Record<string, unknown>> | Array<Record<string, unknown>>>

Une fonction de rappel pour créer une collection à partir du contenu d’un fichier. Utilisez-la lorsque vous devez traiter des fichiers autres que JSON, YAML ou TOML qui ne sont pas pris en charge par défaut (par exemple, .csv) ou lorsque vous utilisez des documents .json imbriqués.

Création d’un chargeur

L’API des chargeurs de contenu est flexible et complète, offrant diverses options de récupération de données. Il est possible de créer des chargeurs simples ou complexes. Votre chargeur personnalisé dépendra à la fois de la source et de la structure de vos données, ainsi que de la manière dont vous choisissez de gérer la couche de persistance des données.

La plupart des chargeurs exporteront une fonction qui accepte des options de configuration et renvoie un objet décrivant un chargeur comprenant un nom (name) pour votre chargeur, une méthode load() et un schema définissant vos entrées.

Charger les collections dans le magasin de données

La fonction load() renvoyée dans l’objet du chargeur définit comment votre contenu est récupéré, analysé, validé et mis à jour. Il accepte un objet context qui vous permet de personnaliser la gestion de vos données de diverses manières et d’interagir avec le magasin de données. Une fonction load() typique va :

• Récupérer vos données à partir d’une source.
• Effacer le magasin de données existant.
• Analyser et valider vos données selon un schéma fourni.
• Mettre à jour le magasin de données avec les nouvelles entrées.

La méthode load() fournit également des fonctions utilitaires pour enregistrer des messages dans la console, générer du contenu en HTML, surveiller les modifications en mode développement et recharger les données, donner accès aux métadonnées et même à la configuration complète d’Astro, et bien plus encore.

Consultez la liste complète des propriétés de LoaderContext pour connaître toutes les options disponibles pour la fonction load().

Fournir un schéma

La fourniture d’un schema Zod dans votre chargeur vous permet de valider les entrées de contenu récupérées avec parseData() avant de les ajouter au magasin de données. Ce schéma sera également utilisé comme schéma par défaut de la collection si aucun schéma n’est défini dans src/content.config.ts, afin de garantir la sûreté du typage et l’accès aux outils de l’éditeur. Vous n’avez pas non plus besoin de définir un schéma dans la collection de contenu si le chargeur fournit cette propriété.

Toutefois, si la collection de contenu définit également un schéma, ce schéma sera utilisé à la place de celui de votre chargeur. Ceci permet aux utilisateurs de votre chargeur d’étendre son schéma ou de transformer des données pour leurs projets. Si vous publiez et distribuez un chargeur, vous souhaiterez peut-être documenter ce comportement et inciter les utilisateurs à ne pas définir eux-mêmes de schéma de collection, ou leur indiquer comment le faire en toute sécurité s’ils ont besoin de données renvoyées dans un format différent.

Si vous devez générer dynamiquement le schéma en fonction des options de configuration ou en introspectant une API, vous pouvez utiliser createSchema() à la place.

Exemple de chargeur

L’exemple suivant montre un chargeur qui récupère des données à partir d’une URL de flux fournie (à l’aide d’un utilitaire loadFeedData personnalisé) et met à jour le magasin de données avec de nouvelles entrées à chaque fois que le site est compilé :

src/feed-loader.ts

// 1. Importer le type `Loader` et toutes les autres dépendances nécessaires.
import type { Loader } from 'astro/loaders';
import { z } from 'astro/zod';
import { loadFeedData } from "./feed.js";

// 2. Définir les options requises par votre chargeur
export function feedLoader(options: { url: string, apiKey: string }) {
  const feedUrl = new URL(options.url);
  // 3. Renvoyer un objet décrivant le chargeur
  return {
    name: "feed-loader",
    load: async ({ store, parseData }) => {
      const feed = await loadFeedData(feedUrl, options.apiKey);

      store.clear();

      for (const item of feed.items) {
        const id = item.guid;
        const data = await parseData({
          id,
          data: item,
        });
        store.set({
          id,
          data,
        });
      }
    },
    // 4. Définir le schéma d'une entrée.
    schema: z.object({
      // ...
    })
  } satisfies Loader;
}

Définir votre collection avec votre chargeur

Utilisez votre chargeur personnalisé comme valeur pour la propriété loader lorsque vous définissez votre collection dans src/content.config.ts. Les options de configuration peuvent être transmises à votre chargeur en tant qu’arguments :

src/content.config.ts

import { defineCollection } from 'astro:content';
import { feedLoader } from './feed-loader.ts';

const blog = defineCollection({
  loader: feedLoader({
    url: "https://api.example.com/articles",
    apiKey: "mon-secret",
  }),
});

export const collections = { blog };

Définir un chargeur sous forme de fonction

Pour les extractions de données simples qui ne nécessitent pas de gestion personnalisée du magasin de données, de validation, de journalisation ou d’autres aides fournies par l’objet de chargeur utilisé lors de la compilation, vous pouvez définir votre chargeur sous forme de fonction.

La fonction peut être asynchrone et doit renvoyer soit un tableau d’entrées contenant chacune un champ id unique, soit un objet où chaque nom de propriété est un identifiant unique et chaque valeur représente l’entrée.

Ce modèle fournit un raccourci pratique pour accomplir les tâches de base normalement effectuées par la fonction load() pour charger les collections dans le magasin de données. Lors de la compilation, le chargeur effacera automatiquement le magasin de données et rechargera toutes les entrées. Aucune autre option de personnalisation ni fonction utilitaire pour la gestion des données n’est fournie.

Ces chargeurs sont souvent suffisamment simples pour que vous puissiez choisir de les définir directement dans le fichier src/content.config.ts :

src/content.config.ts

import { defineCollection } from "astro:content";

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 dont les noms de propriétés sont les identifiants et les valeurs les entrées
    return data.map((country) => ({
      id: country.cca3,
      ...country,
    }));
  },
});

export const collections = { countries };

Chargeurs en direct

L’API des chargeurs en direct est conçue pour interroger n’importe quelle donnée en temps réel. Les chargeurs en direct peuvent filtrer les données entrantes et vérifier leur contenu en garantissant la sûreté du typage. Étant donné que les chargeurs en direct récupèrent des données à jour à chaque requête, il n’y a pas de magasin de données à mettre à jour. Ces chargeurs sont conçus pour renvoyer soit des données, soit un objet Error afin de vous permettre de gérer les erreurs en douceur.

Création d’un chargeur en direct

La plupart des chargeurs en direct exporteront une fonction qui accepte des options de configuration et renvoie un objet décrivant un chargeur en direct comprenant un nom pour votre chargeur et deux méthodes pour définir comment charger votre collection d’entrées et comment charger une seule entrée : loadCollection() et loadEntry().

Chargement des données en direct

Pour renvoyer des données à propos de votre collection, vous devez fournir une fonction loadCollection() qui récupère les données et renvoie un tableau d’entrées (entries) de contenu ou une erreur.

Pour renvoyer une seule entrée de collection en direct, vous devez fournir une fonction loadEntry() qui récupère des données filtrées pour un id donné et renvoie une seule entrée (entry), undefined ou une erreur.

La récupération des données pour ces deux fonctions est généralement effectuée à l’aide d’une instruction try...catch pour gérer les erreurs lors de l’accès aux données en direct.

Consultez l’intégralité de l’API des chargeurs en direct pour en savoir plus sur les fonctions et les types disponibles pour la création de votre chargeur en direct.

Fourniture d’un schéma pour les chargeurs en direct

Les chargeurs en direct ne comportent pas de propriété de schéma. Vous pouvez toutefois garantir la sûreté du typage en définissant un schéma Zod pour votre collection dans src/live.config.ts, ou en transmettant des types génériques à l’interface LiveLoader pour les données qu’ils renvoient.

Exemple de chargeur en direct

L’exemple suivant montre un chargeur en direct qui définit la récupération de données à partir d’un CMS (à l’aide d’un utilitaire fetchFromCMS personnalisé) pour une collection d’entrées et une entrée unique, incluant la sûreté du typage et la gestion des erreurs :

src/article-loader.ts

import type { LiveLoader } from 'astro/loaders';
import { fetchFromCMS } from './cms-client.js';

interface Article {
  id: string;
  title: string;
  htmlContent: string;
  author: string;
}

interface EntryFilter {
  id: string;
}

interface CollectionFilter {
  author?: string;
}

export function articleLoader(config: { apiKey: string }): LiveLoader<Article, EntryFilter, CollectionFilter> {
  return {
    name: 'article-loader',
    loadCollection: async ({ filter }) => {
      try {
        const articles = await fetchFromCMS({
          apiKey: config.apiKey,
          type: 'article',
          filter,
        });

        return {
          entries: articles.map((article) => ({
            id: article.id,
            data: article,
          })),
        };
      } catch (error) {
        return {
          error: new Error('Impossible de charger les articles', { cause: error }),
        };
      }
    },
    loadEntry: async ({ filter }) => {
      try {
        // Le filtre sera { id: "un-id" } lorsqu'il sera appelé avec une chaîne de caractères.
        const article = await fetchFromCMS({
          apiKey: config.apiKey,
          type: 'article',
          id: filter.id,
        });

        if (!article) {
          return {
            error: new Error('Article introuvable'),
          };
        }

        return {
          id: article.id,
          data: article,
          rendered: {
            html: article.htmlContent,
          },
        };
      } catch (error) {
        return {
          error: new Error("Impossible de charger l'article", { cause: error }),
        };
      }
    },
  };
}

Définir votre collection en direct avec votre chargeur

Utilisez votre chargeur en direct personnalisé comme valeur de la propriété loader lorsque vous définissez votre collection dans src/live.config.ts. Les options de configuration peuvent être transmises à votre chargeur en tant qu’arguments :

src/live.config.ts

import { defineLiveCollection } from 'astro:content';
import { articleLoader } from './article-loader.ts';

const blog = defineLiveCollection({
  loader: articleLoader({
    apiKey: "mon-secret",
  }),
});

export const collections = { blog };

Gestion des erreurs dans les chargeurs en direct

Les chargeurs en direct renvoient une sous-classe Error pour les erreurs. Vous pouvez créer des types d’erreurs personnalisés et les utiliser pour une gestion des erreurs plus spécifique si nécessaire. Si une erreur est émise dans le chargeur en direct, elle sera interceptée et renvoyée, encapsulée dans un LiveCollectionError.

Astro générera lui-même certaines erreurs, en fonction de la réponse du chargeur en direct :

• Si loadEntry renvoie undefined, Astro renverra une erreur LiveEntryNotFoundError à l’utilisateur.
• Si un schéma est défini pour la collection et que les données ne correspondent pas au schéma, Astro renverra une erreur LiveCollectionValidationError.
• Si le chargeur renvoie une indication de cache invalide, Astro renverra une exception LiveCollectionCacheHintError. Le champ cacheHint est facultatif ; si vous n’avez pas de données valides à renvoyer, vous pouvez simplement l’omettre.

mon-chargeur.ts

import type { LiveLoader } from 'astro/loaders';
import type { MyData } from "./types";
import { MyLoaderError } from './errors';

export function myLoader(config): LiveLoader<MyData, never, never, MyLoaderError> {
  return {
    name: 'mon-chargeur',
    loadCollection: async () => {
      // Renvoyer votre type d'erreur personnalisé
      return {
        error: new MyLoaderError('Échec du chargement', 'LOAD_ERROR'),
      };
    },
    // ...
  };
}

Création des types d’erreurs du chargeur en direct

Vous pouvez créer des types d’erreurs personnalisés pour les erreurs renvoyées par votre chargeur et les transmettre en tant que type générique pour obtenir un typage correct :

mon-chargeur.ts

import type { LiveLoader } from "astro/loaders";
import type { MyData } from "./types"

export class MyLoaderError extends Error {
  constructor(message: string, public code?: string) {
    super(message);
    this.name = 'MyLoaderError';
  }
}

export function myLoader(config): LiveLoader<MyData, never, never, MyLoaderError> {
  return {
    name: 'mon-chargeur',
    loadCollection: async () => {
      // Renvoyer votre type d'erreur personnalisé
      return {
        error: new MyLoaderError('Échec du chargement', 'LOAD_ERROR'),
      };
    },
    // ...
  };
}

Lorsque vous utilisez getLiveCollection() ou getLiveEntry(), TypeScript déduira le type d’erreur personnalisé, vous permettant ainsi de gérer l’erreur de manière appropriée :

---
export const prerender = false; // Pas nécessaire en mode `server`

import { getLiveEntry } from 'astro:content';
import { MyLoaderError } from "../my-loader";

const { entry, error } = await getLiveEntry('products', '123');

if (error) {
  if (error instanceof MyLoaderError) {
    console.error(`Erreur du chargeur : ${error.message} (code : ${error.code})`);
  } else {
    console.error(`Erreur inattendue : ${error.message}`);
  }
  return Astro.rewrite('/500');
}
---

Définition de types de filtres personnalisés

Les chargeurs en direct peuvent définir des types de filtres personnalisés pour getLiveCollection() et getLiveEntry(). Cela permet d’effectuer des requêtes bénéficiant de la sûreté du typage et adaptées aux capacités de votre API, ce qui facilite la découverte des filtres disponibles par les utilisateurs et leur permet de s’assurer de leur utilisation correcte. Si vous incluez des commentaires JSDoc dans les types de vos filtres, l’utilisateur les verra dans son IDE sous forme d’indications lors de l’utilisation du chargeur.

store-loader.ts

import type { LiveLoader } from 'astro/loaders';
import { fetchProduct, fetchCategory, type Product } from './store-client';

interface CollectionFilter {
  category?: string;
  /** Prix minimum pour filtrer les produits */
  minPrice?: number;
  /** Prix maximum pour filtrer les produits */
  maxPrice?: number;
}

interface EntryFilter {
  /** Alias pour `sku` */
  id?: string;
  slug?: string;
  sku?: string;
}

export function productLoader(config: {
  apiKey: string;
  endpoint: string;
}): LiveLoader<Product, EntryFilter, CollectionFilter> {
  return {
    name: 'product-loader',
    loadCollection: async ({ filter }) => {
      // Le filtre est de type `CollectionFilter`
      const data = await fetchCategory({
        apiKey: config.apiKey,
        category: filter?.category ?? 'all',
        minPrice: filter?.minPrice,
        maxPrice: filter?.maxPrice,
      });

      return {
        entries: data.products.map((product) => ({
          id: product.sku,
          data: product,
        })),
      };
    },
    loadEntry: async ({ filter }) => {
      // Le filtre est de type `EntryFilter | { id: string }`
      const product = await fetchProduct({
        apiKey: config.apiKey,
        slug: filter.slug,
        sku: filter.sku || filter.id,
      });
      if (!product) {
        return {
          error: new Error('Produit introuvable'),
        };
      }
      return {
        id: product.sku,
        data: product,
      };
    },
  };
}

Indications de cache

Les chargeurs en direct peuvent fournir des indications de cache pour faciliter la mise en cache des réponses. Vous pouvez utiliser ces données pour envoyer des en-têtes de cache HTTP ou pour orienter votre stratégie de mise en cache.

mon-chargeur.ts

import type { LiveLoader } from "astro/loaders";
import { loadStoreProduct, loadStoreProducts, getLastModifiedDate } from "./store";
import type { Product, ProductEntryFilter, ProductCollectionFilter } from "./types";

export function myLoader(config): LiveLoader<Product, ProductEntryFilter, ProductCollectionFilter> {
  return {
    name: 'cached-loader',
    loadCollection: async ({ filter }) => {
      const products = await loadStoreProducts(filter);
      return {
        entries: products.map((item) => ({
          id: item.id,
          data: item,
          // Vous pouvez éventuellement fournir des indications de cache pour chaque entrée.
          cacheHint: {
            tags: [`produit-${item.id}`, `categorie-${item.category}`],
          },
        })),
        cacheHint: {
          // Tous les champs sont facultatifs et sont combinés aux indications de cache de chaque entrée.
          // Les étiquettes (`tags`) sont fusionnées à partir de toutes les entrées
          // `lastModified` est la dernière valeur de `lastModified` dans toutes les entrées et dans la collection
          lastModified: getLastModifiedDate(products),
          tags: ['produits'],
        },
      };
    },
    loadEntry: async ({ filter }) => {
      const item = await loadStoreProduct(filter);
      return {
        id: item.id,
        data: item,
        cacheHint: {
          lastModified: new Date(item.lastModified),
          tags: [`produit-${item.id}`, `categorie-${item.category}`],
        },
      };
    },
  };
}

Vous pouvez ensuite utiliser ces indications dans vos pages. Si vous avez activé la mise en cache expérimentale des routes (EN), transmettez directement les indications de cache à Astro.cache.set() :

src/pages/boutique/[id].astro

---
export const prerender = false; // Pas nécessaire en mode `server`

import { getLiveEntry } from 'astro:content';

const { entry, error, cacheHint } = await getLiveEntry('produits', Astro.params.id);

if (error) {
  return Astro.redirect('/404');
}

// Transmettre les indications de cache à la mise en cache des routes
if (cacheHint) {
  Astro.cache.set(cacheHint);
}
Astro.cache.set({ maxAge: 300 });
---

<h1>{entry.data.name}</h1>
<p>{entry.data.description}</p>

Sans la mise en cache des routes activée, vous pouvez utiliser des indications de cache pour définir manuellement les en-têtes de réponse pour votre propre stratégie de mise en cache :

src/pages/boutique/[id].astro

---
export const prerender = false; // Pas nécessaire en mode `server`

import { getLiveEntry } from 'astro:content';

const { entry, error, cacheHint } = await getLiveEntry('produits', Astro.params.id);

if (error) {
  return Astro.redirect('/404');
}

if (cacheHint?.tags) {
  Astro.response.headers.set('Cache-Tag', cacheHint.tags.join(','));
}

if (cacheHint?.lastModified) {
  Astro.response.headers.set('Last-Modified', cacheHint.lastModified.toUTCString());
}
---

<h1>{entry.data.name}</h1>
<p>{entry.data.description}</p>

Note

Les indications de cache n’entraînent pas automatiquement la mise en cache de la réponse par Astro. Elles fournissent des valeurs que vous pouvez transmettre à la mise en cache des routes (EN) ou utiliser pour implémenter votre propre stratégie de mise en cache.

Distribuer votre chargeur

Les chargeurs peuvent être définis dans votre site ou sous forme de paquet npm distinct. Si vous souhaitez partager votre chargeur avec la communauté, vous pouvez le publier sur npm avec les mots-clés withastro et astro-loader.

Un chargeur doit exporter une fonction qui renvoie un objet LiveLoader pour les chargeurs en direct ou un objet Loader pour les chargeurs appelés lors de la compilation, permettant aux utilisateurs de le configurer avec leurs propres paramètres.

API des chargeurs sous forme d’objet

Ajouté à la version : astro@5.0.0

Cette section présente l’API permettant de définir un chargeur sous forme d’objet appelé lors de la compilation.

L’objet Loader

Type : Loader

Une fonction de chargeur renvoie un objet comportant deux propriétés obligatoires. En plus de fournir un nom pour le chargeur, cet objet décrit comment récupérer les données de la collection.

Vous pouvez également renvoyer une troisième propriété définissant un schéma pour valider les entrées de votre collection. Utilisez l’opérateur satisfies de TypeScript au lieu d’une annotation de type de retour afin de garantir la sûreté du typage au sein de votre objet de chargeur et de préserver l’inférence de type lorsque celui-ci est utilisé dans une collection.

Loader.name

Type : string

Ajouté à la version : astro@5.0.0

Un nom unique pour le chargeur, utilisé dans les logs et pour le chargement conditionnel.

Loader.load()

Type : (context: LoaderContext) => Promise<void>

Ajouté à la version : astro@5.0.0

Une fonction asynchrone appelée lors de la compilation pour charger les données et mettre à jour le magasin. Elle reçoit un objet LoaderContext contenant des fonctions et propriétés utilitaires pour l’implémentation du chargeur, ainsi que la base de données store et les méthodes permettant d’interagir avec elle.

Loader.schema

Type : ZodSchema | Promise<ZodSchema> | (() => ZodSchema | Promise<ZodSchema>)

Ajouté à la version : astro@5.0.0

Un schéma Zod facultatif qui définit la forme des entrées. Il est utilisé à la fois pour valider les données et pour générer des types TypeScript pour la collection.

Lorsque vous devez générer dynamiquement le schéma au moment de la compilation en fonction des options de configuration ou en introspectant une API, utilisez plutôt createSchema().

Si la propriété est présente, elle sera remplacée par tout schéma Zod défini pour la collection dans le fichier src/content.config.ts.

Loader.createSchema()

Type : () => Promise<{ schema: ZodSchema; types: string }>

Ajouté à la version : astro@6.0.0 Nouveau

Une fonction asynchrone optionnelle qui renvoie un objet contenant un schéma Zod et des types. Elle permet de générer dynamiquement le schéma lors de la compilation, en fonction des options de configuration ou par introspection d’une API.

Lorsque vous n’avez besoin de fournir qu’un schéma statique, fournissez plutôt un objet de validation Zod en utilisant schema.

Si elle est présente, elle sera remplacée par tout schéma Zod défini pour la collection dans le fichier src/content.config.ts.

Le contenu de types renvoyé sera écrit dans un fichier TypeScript et devra exporter un type ou une interface Entry :

src/feed-loader.ts

import type { Loader } from 'astro/loaders';
import { z } from 'astro/zod';
import { loadFeedData, getSchema, getTypes } from "./feed.js";

export function myLoader(options: { url: string, apiKey: string }) {
  const feedUrl = new URL(options.url);

  return {
    name: "feed-loader",
    load: async ({ store, parseData }) => {
      const feed = await loadFeedData(feedUrl, options.apiKey);

      store.clear();

      for (const item of feed.items) {
        const id = item.guid;
        const data = await parseData({
          id,
          data: item,
        });
        store.set({
          id,
          data,
        });
      }
    },
    createSchema: async () => {
      const schema = await getSchema();
      const types = await getTypes();

      return {
        schema,
        types: `export type Entry = ${types}`,
      };
    },
  } satisfies Loader;
}

LoaderContext

Cet objet est passé à la méthode load() du chargeur et contient les propriétés suivantes :

LoaderContext.collection

Type : string

Ajouté à la version : astro@5.0.0

Le nom unique de la collection. Il s’agit de la clé dans l’objet collections dans le fichier src/content.config.ts.

LoaderContext.store

Type : DataStore

Ajouté à la version : astro@5.0.0

Une magasin de données pour stocker les données réelles. Utilisez-le pour mettre à jour le magasin avec de nouvelles entrées. Voir DataStore pour plus d’informations.

LoaderContext.meta

Type : MetaStore

Ajouté à la version : astro@5.0.0

Un magasin de clés-valeurs avec une portée limitée à la collection, conçu pour des choses comme la synchronisation des jetons et des heures de dernière modification. Ces métadonnées sont conservées entre les compilations avec les données de la collection, mais ne sont disponibles qu’à l’intérieur du chargeur.

const lastModified = meta.get("lastModified");
// ...
meta.set("lastModified", new Date().toISOString());

LoaderContext.logger

Type : AstroIntegrationLogger

Ajouté à la version : astro@5.0.0

Un outil de journalisation permettant d’enregistrer des messages dans la console. Utilisez-le plutôt que console.log pour obtenir des journaux plus détaillés contenant des informations spécifiques au chargeur, comme son nom ou des détails sur le processus de chargement. Consultez AstroIntegrationLogger pour plus d’informations.

Extrait du chargeur file()

return {
  name: 'file-loader',
  load: async ({ config, store, logger, watcher }) => {
    const url = new URL(fileName, config.root);
    const filePath = fileURLToPath(url);
    await syncData(filePath, store);

    watcher?.on('change', async (changedPath) => {
      if (changedPath === filePath) {
        logger.info(`Reloading data from ${fileName}`);
        await syncData(filePath, store);
      }
    });
  },
};

LoaderContext.config

Type : AstroConfig

Ajouté à la version : astro@5.0.0

L’objet de configuration d’Astro complet et résolu avec toutes les valeurs par défaut appliquées. Consultez la référence de configuration pour plus d’informations.

Extrait du chargeur file()

return {
  name: 'file-loader',
  load: async ({ config, store, logger, watcher }) => {
    const url = new URL(fileName, config.root);
    const filePath = fileURLToPath(url);
    await syncData(filePath, store);

    watcher?.on('change', async (changedPath) => {
      if (changedPath === filePath) {
        logger.info(`Reloading data from ${fileName}`);
        await syncData(filePath, store);
      }
    });
  },
};

LoaderContext.parseData()

Type : (props: ParseDataOptions<TData>) => Promise<TData>

Ajouté à la version : astro@5.0.0

Valide et analyse les données conformément au schéma de la collection. Transmettez les données à cette fonction pour les valider et les analyser avant de les stocker dans le magasin de données.

loader.ts

import type { Loader } from "astro/loaders";
import { loadFeed } from "./feed.js";

export function feedLoader({ url }) {
  const feedUrl = new URL(url);
  return {
    name: "feed-loader",
    load: async ({ store, logger, parseData, meta, generateDigest }) => {
      logger.info("Chargement des articles");
      const feed = loadFeed(feedUrl);
      store.clear();

      for (const item of feed.items) {
        const id = item.guid;
        const data = await parseData({
          id,
          data: item,
        });
        store.set({
          id,
          data,
        });
      }
    },
  } satisfies Loader;
}

LoaderContext.renderMarkdown()

Type : (content: string, options?: { fileURL?: URL }) => Promise<RenderedContent>

Ajouté à la version : astro@5.9.0

Restitue une chaîne Markdown en HTML, renvoyant un objet RenderedContent.

Cela vous permet de restituer le contenu Markdown directement dans vos chargeurs en utilisant le même traitement Markdown que le chargeur glob() intégré d’Astro et donne accès à la fonction render() et au composant <Content /> pour la restitution du contenu.

Attribuez cet objet au champ rendered de l’objet DataEntry pour permettre aux utilisateurs d’afficher le contenu dans une page. Si le contenu Markdown inclut un frontmatter, celui-ci sera analysé et disponible dans metadata.frontmatter. Les métadonnées seront exclues du rendu HTML.

loader.ts

import type { Loader } from 'astro/loaders';
import { loadFromCMS } from './cms.js';

export function myLoader(settings) {
  return {
    name: 'cms-loader',
    async load({ renderMarkdown, store }) {
      const entries = await loadFromCMS();

      store.clear();

      for (const entry of entries) {
        store.set({
          id: entry.id,
          data: entry,
          // Suppose que chaque entrée possède un champ `content` avec du contenu Markdown
          rendered: await renderMarkdown(entry.content),
        });
      }
    },
  } satisfies Loader;
}

fileURL

Type : URL

Ajouté à la version : astro@6.0.0 Nouveau

Spécifie le chemin d’accès vers le fichier à utiliser pour résoudre les chemins d’image relatifs dans le contenu Markdown.

L’exemple suivant utilise le répertoire racine configuré pour résoudre les chemins d’accès aux images :

loader.ts

for (const file of files) {
  const content = await readFile(file.path, 'utf8');
  store.set({
    id: file.id,
    data: file.data,
    rendered: await renderMarkdown(content, {
      fileURL: new URL(file.path, config.root),
    }),
  });
}

LoaderContext.generateDigest()

Type : (data: Record<string, unknown> | string) => string

Ajouté à la version : astro@5.0.0

Génère un résumé de contenu non cryptographique d’un objet ou d’une chaîne de caractères. Cela peut être utilisé pour suivre si les données ont changé en définissant le champ digest d’une entrée.

loader.ts

import type { Loader } from "astro/loaders";
import { loadFeed } from "./feed.js";

export function feedLoader({ url }) {
  const feedUrl = new URL(url);
  return {
    name: "feed-loader",
    load: async ({ store, logger, parseData, meta, generateDigest }) => {
      logger.info("Chargement des articles");
      const feed = loadFeed(feedUrl);
      store.clear();

      for (const item of feed.items) {
        const id = item.guid;
        const data = await parseData({
          id,
          data: item,
        });

        const digest = generateDigest(data);

        store.set({
          id,
          data,
          digest,
        });
      }
    },
  } satisfies Loader;
}

LoaderContext.watcher

Type : FSWatcher

Ajouté à la version : astro@5.0.0

En mode dev, il s’agit d’un observateur de système de fichiers qui peut être utilisé pour déclencher des mises à jour. Voir ViteDevServer pour plus d’informations.

Extrait du chargeur file()

return {
  name: 'file-loader',
  load: async ({ config, store, watcher }) => {
    const url = new URL(fileName, config.root);
    const filePath = fileURLToPath(url);
    await syncData(filePath, store);

    watcher?.on('change', async (changedPath) => {
      if (changedPath === filePath) {
        logger.info(`Reloading data from ${fileName}`);
        await syncData(filePath, store);
      }
    });
  },
};

LoaderContext.refreshContextData

Type : Record<string, unknown>

Ajouté à la version : astro@5.0.0

Si le chargeur a été déclenché par une intégration, il peut éventuellement contenir des données supplémentaires définies par cette intégration. Il n’est défini que lorsque le chargeur est déclenché par une intégration. Consultez la référence du hook astro:server:setup pour plus d’informations.

loader.ts

import type { Loader } from "astro/loaders";
import { processWebhook } from "./lib/webhooks";

export function myLoader(options: { url: string }) {
  return {
    name: "mon-chargeur",
    load: async ({ refreshContextData, store, logger }) => {
      if(refreshContextData?.webhookBody) {
        logger.info("Webhook déclenché avec le corps");
        processWebhook(store, refreshContextData.webhookBody);
      }
      // ...
    },
  } satisfies Loader;
}

DataStore

Le magasin de données est l’interface d’un chargeur vers les données de la collection de contenu. Il s’agit d’un magasin clé-valeur (abrégé KV en anglais), limité à la collection, et par conséquent, un chargeur ne peut accéder qu’aux données de sa propre collection.

DataStore.get()

Type : (key: string) => DataEntry | undefined

Ajouté à la version : astro@5.0.0

Obtenir une entrée du magasin par son ID. Renvoie undefined si l’entrée n’existe pas.

const existingEntry = store.get("my-entry");

L’objet renvoyé est un objet DataEntry.

DataStore.set()

Type : (entry: DataEntry) => boolean

Ajouté à la version : astro@5.0.0

Utilisé après que les données ont été validées et analysées pour ajouter une entrée au magasin, renvoyant true si l’entrée a été définie. Renvoie false lorsque la propriété digest détermine qu’une entrée n’a pas changé et ne doit pas être mise à jour.

loader.ts

    for (const item of feed.items) {
      const id = item.guid;
      const data = await parseData({
        id,
        data: item,
      });
      const digest = generateDigest(data);
      store.set({
        id,
        data,
        rendered: {
          html: data.description ?? "",
        },
        digest,
      });
    }

DataStore.entries()

Type : () => Array<[id: string, DataEntry]>

Ajouté à la version : astro@5.0.0

Obtenir toutes les entrées de la collection sous forme de tableau de paires clé-valeur.

DataStore.keys()

Type : () => Array<string>

Ajouté à la version : astro@5.0.0

Obtenir toutes les clés des entrées de la collection.

DataStore.values()

Type : () => Array<DataEntry>

Ajouté à la version : astro@5.0.0

Obtenir toutes les entrées de la collection sous forme de tableau.

DataStore.delete()

Type : (key: string) => void

Ajouté à la version : astro@5.0.0

Supprimer une entrée du magasin par son ID.

DataStore.clear()

Type : () => void

Ajouté à la version : astro@5.0.0

Effacer toutes les entrées de la collection.

DataStore.has()

Type : (key: string) => boolean

Ajouté à la version : astro@5.0.0

Vérifier si une entrée existe dans le magasin par son ID.

DataEntry

Il s’agit du type d’objet stocké dans le magasin de données. Il possède les propriétés suivantes :

DataEntry.id

Type : string

Ajouté à la version : astro@5.0.0

Un identifiant pour l’entrée, qui doit être unique dans la collection. Il est utilisé pour rechercher l’entrée dans le magasin et constitue la clé utilisée avec getEntry() pour cette collection.

DataEntry.data

Type : Record<string, unknown>

Ajouté à la version : astro@5.0.0

Les données réelles de l’entrée. Lorsqu’un utilisateur accède à la collection, des types TypeScript seront générés selon le schéma de la collection.

Il est de la responsabilité du chargeur d’utiliser parseData() pour valider et analyser les données avant de les stocker dans le magasin de données : aucune validation n’est effectuée lors de l’obtention ou de la définition des données.

DataEntry.filePath

Type : string | undefined

Ajouté à la version : astro@5.0.0

Chemin d’accès au fichier source de cette entrée, par rapport à la racine du site. Cela s’applique uniquement aux chargeurs basés sur des fichiers et est utilisé pour résoudre des chemins tels que des images ou d’autres ressources.

S’il n’est pas défini, tous les champs du schéma qui utilisent l’assistant image() seront traités comme des chemins publics et non transformés.

DataEntry.body

Type : string | undefined

Ajouté à la version : astro@5.0.0

Le corps brut de l’entrée, le cas échéant. Si l’entrée inclut du contenu rendu, ce champ peut être utilisé pour stocker la source brute. Ceci est facultatif et n’est pas utilisé en interne.

DataEntry.digest

Type : string | undefined

Ajouté à la version : astro@5.0.0

Un résumé facultatif du contenu de l’entrée qui peut être utilisé pour vérifier si les données ont changé.

Lors de la définition d’une entrée, l’entrée ne sera mise à jour que si le résumé ne correspond pas à une entrée existante avec le même ID.

Le format du résumé dépend du chargeur, mais il doit s’agir d’une chaîne de caractères qui change lorsque les données changent. Cela peut être fait avec la fonction generateDigest.

DataEntry.rendered

Type : RenderedContent | undefined

Ajouté à la version : astro@5.0.0

Stocke un objet avec le contenu rendu et les métadonnées d’une entrée si elle a été rendue au format HTML. Par exemple, cela peut être utilisé pour stocker le contenu rendu d’une entrée Markdown ou du code HTML d’un CMS.

Si ce champ est fourni, alors la fonction render() et le composant <Content /> sont disponibles pour restituer l’entrée dans une page.

Si l’entrée contient du contenu Markdown, vous pouvez utiliser la fonction renderMarkdown() pour générer cet objet à partir de la chaîne de caractères au format Markdown.

DataEntry.rendered.html

Type : string

Contient la chaîne de caractères rendue au format HTML. Celle-ci est utilisée par render() pour renvoyer un composant qui effectue le rendu de ce HTML.

DataEntry.rendered.metadata

Type : object | undefined

Décrit les métadonnées présentes dans ce fichier. Cela inclut les chemins d’accès aux images (imagePaths), les titres (headings), le frontmatter et toutes autres métadonnées présentes dans le fichier. Si le fichier n’a pas été rendu au format HTML, cette valeur sera undefined.

DataEntry.rendered.metadata.imagePaths

Type : string[]

Spécifie la liste des chemins d’accès aux images présentes dans cette entrée. Chaque chemin est relatif au chemin de l’entrée (filePath).

DataEntry.rendered.metadata.headings

Type : MarkdownHeading[]

Spécifie la liste des titres présents dans ce fichier. Chaque titre est décrit par une profondeur (depth) déterminée par le niveau du titre (h1 -> h6), un slug généré avec github-slugger, et son contenu (text).

DataEntry.rendered.metadata.frontmatter

Type : Record<string, any>

Décrit le frontmatter brut, analysé à partir du fichier. Cela peut inclure des données injectées par programmation à partir de modules d’extension Remark.

API des chargeurs en direct

Ajouté à la version : astro@6.0.0 Nouveau

Cette section présente l’API permettant de définir un chargeur en direct.

L’objet LiveLoader

Type : LiveLoader<TData, TEntryFilter, TCollectionFilter, TError>

Ajouté à la version : astro@6.0.0 Nouveau

Une fonction de chargeur en direct renvoie un objet comportant trois propriétés obligatoires. En plus de fournir un nom pour le chargeur, cet objet décrit comment récupérer des entrées individuelles et une collection entière à partir de votre source de données en direct.

Utilisez le type générique LiveLoader pour garantir la sûreté du typage dans votre chargeur. Ce type accepte les paramètres de type suivants, dans cet ordre :

• TData (par défaut Record<string, unknown>) : La structure de données de chaque entrée renvoyée par le chargeur.
• TEntryFilter (par défaut : never) : Type d’objet filtre accepté par getLiveEntry() et accessible dans loadEntry(). Utilisez never si vous ne prenez pas en charge le filtrage des entrées individuelles.
• TCollectionFilter (par défaut : never) : Type d’objet filtre accepté par getLiveCollection() et accessible dans loadCollection(). Utilisez never lorsque vous ne prenez pas en charge le filtrage des collections.
• TError (par défaut Error) : Une classe Error personnalisée qui peut être renvoyée par le chargeur pour une gestion des erreurs plus granulaire.

LiveLoader.name

Type : string

Ajouté à la version : astro@6.0.0 Nouveau

Un nom unique pour le chargeur, utilisé dans les journaux.

LiveLoader.loadCollection()

Type : (context: LoadCollectionContext<TCollectionFilter>) => Promise<LiveDataCollection<TData> | { error: TError; }>

Ajouté à la version : astro@6.0.0 Nouveau

Définit une méthode pour charger une collection d’entrées. Cette fonction reçoit un objet de contexte contenant une propriété filter facultative et doit renvoyer les données associées à cette collection ou les erreurs.

LiveLoader.loadEntry()

Type : (context: LoadEntryContext<TEntryFilter>) => Promise<LiveDataEntry<TData> | undefined | { error: TError; }>

Ajouté à la version : astro@6.0.0 Nouveau

Définit une méthode pour charger une seule entrée. Cette fonction reçoit un objet de contexte contenant une propriété filter et renvoie soit les données associées à l’entrée demandée, undefined lorsque l’entrée est introuvable, soit les erreurs.

LoadCollectionContext

Type : { filter?: TCollectionFilter; }

Ajouté à la version : astro@6.0.0 Nouveau

Cet objet est transmis à la méthode loadCollection() du chargeur et contient les propriétés suivantes :

LoadCollectionContext.filter

Type : Record<string, any> | never
Default: never

Ajouté à la version : astro@6.0.0 Nouveau

Un objet décrivant les filtres pris en charge par votre chargeur.

LoadEntryContext

Type : { filter: TEntryFilter; }

Ajouté à la version : astro@6.0.0 Nouveau

Cet objet est transmis à la méthode loadEntry() du chargeur et contient les propriétés suivantes :

LoadEntryContext.filter

Type : Record<string, any> | never
Default: never

Ajouté à la version : astro@6.0.0 Nouveau

Un objet décrivant les filtres pris en charge par votre chargeur.

LiveDataEntry

Type : { id: string; data: TData; rendered?: { html: string }; cacheHint?: CacheHint; }

Ajouté à la version : astro@6.0.0 Nouveau

Il s’agit de l’objet de type renvoyé par la méthode loadEntry(). Il contient les propriétés suivantes :

LiveDataEntry.id

Type : string

Ajouté à la version : astro@6.0.0 Nouveau

Un identifiant pour l’entrée, qui doit être unique au sein de la collection. Il s’agit du nom de propriété utilisé avec getLiveEntry() pour cette collection.

LiveDataEntry.data

Type : Record<string, unknown>

Ajouté à la version : astro@6.0.0 Nouveau

Les données réelles de l’entrée. Lorsqu’un utilisateur accède à la collection, des types TypeScript sont générés conformément au schéma de la collection.

Il incombe au chargeur de valider et d’analyser les données avant de les renvoyer.

LiveDataEntry.rendered

Type : { html: string }

Ajouté à la version : astro@6.0.0 Nouveau

Un objet contenant le contenu rendu d’une entrée si celle-ci a été convertie en HTML. Par exemple, il peut s’agir du contenu rendu d’une entrée Markdown ou du code HTML provenant d’un CMS.

Si ce champ est fourni, alors la fonction render() et le composant <Content /> sont disponibles pour afficher l’entrée dans une page.

Si le chargeur ne renvoie pas de propriété rendered pour une entrée, le composant <Content /> ne génèrera rien.

LiveDataEntry.cacheHint

Type : CacheHint

Ajouté à la version : astro@6.0.0 Nouveau

Un objet optionnel fournissant une indication sur la manière de mettre en cache cette entrée spécifique.

LiveDataCollection

Type : { entries: Array<LiveDataEntry<TData>>; cacheHint?: CacheHint; }

Ajouté à la version : astro@6.0.0 Nouveau

Il s’agit du type d’objet renvoyé par la méthode loadCollection(). Il contient les propriétés suivantes :

LiveDataCollection.entries

Type : Array<LiveDataEntry<TData>>

Ajouté à la version : astro@6.0.0 Nouveau

Un tableau d’objets LiveDataEntry.

LiveDataCollection.cacheHint

Type : CacheHint

Ajouté à la version : astro@6.0.0 Nouveau

Un objet optionnel fournissant des indications sur la manière de mettre en cache cette collection. Cet objet sera fusionné avec les indications de cache définies pour chaque entrée individuelle, si elles sont fournies.

CacheHint

Un objet que les chargeurs peuvent renvoyer via la propriété cacheHint dans LiveDataCollection ou LiveDataEntry pour fournir des indications aidant à la mise en cache de la réponse. Cet objet contient les propriétés suivantes :

CacheHint.tags

Type : Array<string>

Ajouté à la version : astro@6.0.0 Nouveau

Un tableau d’identifiants de chaînes de caractères permettant un contrôle précis du cache. Cela vous permet de regrouper du contenu similaire et d’invalider sélectivement les réponses mises en cache lorsque certains contenus sont modifiés.

L’exemple suivant définit des étiquettes d’indication de cache pour une collection d’articles filtrés par auteur :

return {
  /* ... */
  cacheHint: {
    tags: ["articles", `articles-${filter.author}`],
  },
};

CacheHint.lastModified

Type : Date

Ajouté à la version : astro@6.0.0 Nouveau

La date de la dernière modification du contenu (par exemple, la dernière mise à jour d’une entrée dans une collection). Cette date peut être utilisée pour définir des en-têtes de cache HTTP tels que Last-Modified et If-Modified-Since.

L’exemple suivant définit une indication de cache pour un seul produit en utilisant sa date de dernière mise à jour :

return {
  /* ... */
  cacheHint: {
    lastModified: new Date(product.updatedAt)
  },
};