Référence des modules d'extension

Les modules d’extension Starlight peuvent personnaliser la configuration, l’interface utilisateur et le comportement de Starlight, tout en étant faciles à partager et à réutiliser. Cette page de référence documente l’API à laquelle ces modules d’extension ont accès.

Consultez la référence de configuration pour en savoir plus sur l’utilisation d’un module d’extension Starlight ou visitez la vitrine des modules d’extension pour voir une liste de modules d’extension disponibles.

Référence rapide de l’API

Un module d’extension Starlight a la forme suivante. Voir ci-dessous pour plus de détails sur les différentes propriétés et paramètres des hooks.

interface StarlightPlugin {
  name: string;
  hooks: {
    setup: (options: {
      config: StarlightUserConfig;
      updateConfig: (newConfig: StarlightUserConfig) => void;
      addIntegration: (integration: AstroIntegration) => void;
      astroConfig: AstroConfig;
      command: 'dev' | 'build' | 'preview';
      isRestart: boolean;
      logger: AstroIntegrationLogger;
      injectTranslations: (Record<string, Record<string, string>>) => void;
    }) => void | Promise<void>;
  };
}

name

Type : string

Un module d’extension doit fournir un nom unique qui le décrit. Le nom est utilisé lors de l’affichage des messages liés à ce module d’extension et peut être utilisé par d’autres modules d’extension pour détecter la présence de ce dernier.

hooks

Les hooks sont des fonctions que Starlight appelle pour exécuter le code du module d’extension à des moments spécifiques. Actuellement, Starlight prend en charge un seul hook setup.

hooks.setup

La fonction de configuration du module d’extension appelée lorsque Starlight est initialisé (pendant le hook astro:config:setup de l’intégration). Le hook setup peut être utilisé pour mettre à jour la configuration de Starlight ou ajouter des intégrations Astro.

Ce hook est appelé avec les options suivantes :

config

Type : StarlightUserConfig

Une copie en lecture seule de la configuration de Starlight fournie par l’utilisateur. Cette configuration peut avoir été mise à jour par d’autres modules d’extension configurés avant celui en cours.

updateConfig

Type : (newConfig: StarlightUserConfig) => void

Une fonction de rappel pour mettre à jour la configuration de Starlight fournie par l’utilisateur. Spécifiez les clés de configuration de niveau racine que vous souhaitez remplacer. Pour mettre à jour des valeurs de configuration imbriquées, vous devez fournir l’objet imbriqué entier.

Pour étendre une option de configuration existante sans la remplacer, étendez la valeur existante dans votre nouvelle valeur. Dans l’exemple suivant, un nouveau compte de média social est ajouté à la configuration existante en étendant config.social dans le nouvel objet social :

module-extension.ts

export default {
  name: 'ajout-twitter-plugin',
  hooks: {
    setup({ config, updateConfig }) {
      updateConfig({
        social: {
          ...config.social,
          twitter: 'https://twitter.com/astrodotbuild',
        },
      });
    },
  },
};

addIntegration

Type : (integration: AstroIntegration) => void

Une fonction de rappel pour ajouter une intégration Astro requise par le module d’extension.

Dans l’exemple suivant, le module d’extension vérifie d’abord si l’intégration React d’Astro est configurée et, si ce n’est pas le cas, utilise addIntegration() pour l’ajouter :

module-extension.ts

import react from '@astrojs/react';

export default {
  name: 'plugin-utilisant-react',
  hooks: {
    setup({ addIntegration, astroConfig }) {
      const isReactLoaded = astroConfig.integrations.find(
        ({ name }) => name === '@astrojs/react'
      );

      // Ajoute seulement l'intégration React si elle n'est pas déjà chargée.
      if (!isReactLoaded) {
        addIntegration(react());
      }
    },
  },
};

astroConfig

Type : AstroConfig

Une copie en lecture seule de la configuration d’Astro fournie par l’utilisateur.

command

Type : 'dev' | 'build' | 'preview'

La commande utilisée pour exécuter Starlight :

• dev - Le projet est exécuté avec astro dev
• build - Le projet est exécuté avec astro build
• preview - Le projet est exécuté avec astro preview

isRestart

Type : boolean

false lorsque le serveur de développement démarre, true lorsqu’un rechargement est déclenché. Les raisons courantes d’un redémarrage incluent un utilisateur qui modifie son fichier astro.config.mjs pendant que le serveur de développement est en cours d’exécution.

logger

Type : AstroIntegrationLogger

Une instance du journaliseur (logger) d’intégration Astro que vous pouvez utiliser pour écrire des messages de journalisation. Tous les messages seront préfixés par le nom du module d’extension.

module-extension.ts

export default {
  name: 'plugin-long-processus',
  hooks: {
    setup({ logger }) {
      logger.info("Démarrage d'un long processus…");
      // Un long processus…
    },
  },
};

L’exemple ci-dessus affichera un message qui inclut le message d’information fourni :

[plugin-long-processus] Démarrage d'un long processus…

injectTranslations

Type : (translations: Record<string, Record<string, string>>) => void

Une fonction de rappel pour ajouter ou mettre à jour des chaînes de traduction utilisées dans les API de localisation de Starlight.

Dans l’exemple suivant, un module d’extension injecte des traductions pour une chaîne d’interface utilisateur personnalisée nommée myPlugin.doThing pour les locales en et fr :

module-extension.ts

export default {
  name: 'plugin-avec-traductions',
  hooks: {
    setup({ injectTranslations }) {
      injectTranslations({
        en: {
          'myPlugin.doThing': 'Do the thing',
        },
        fr: {
          'myPlugin.doThing': 'Faire le truc',
        },
      });
    },
  },
};

Pour utiliser les traductions injectées dans l’interface utilisateur de votre module d’extension, suivez le guide « Utiliser les traductions de l’interface utilisateur ».

Le typage des chaînes de traduction injectées pour un module d’extension est généré automatiquement dans le projet d’un utilisateur, mais n’est pas encore disponible lors du développement dans le code source de votre module d’extension. Pour typer l’objet locals.t dans le contexte de votre module d’extension, déclarez les espaces de noms globaux suivants dans un fichier de déclaration TypeScript :

env.d.ts

declare namespace App {
  type StarlightLocals = import('@astrojs/starlight').StarlightLocals;
  // Definit l'objet `locals.t` dans le contexte d'un module d'extension.
  interface Locals extends StarlightLocals {}
}

declare namespace StarlightApp {
  // Définit les traductions supplémentaires du module d'extension dans l'interface `I18n`.
  interface I18n {
    'myPlugin.doThing': string;
  }
}

Vous pouvez également inférer le typage de l’interface StarlightApp.I18n à partir d’un fichier source si vous avez un objet contenant vos traductions.

Par exemple, étant donné le fichier source suivant :

traductions.ts

export const UIStrings = {
  en: { 'myPlugin.doThing': 'Do the thing' },
  fr: { 'myPlugin.doThing': 'Faire le truc' },
};

La déclaration suivante inférerait le typage à partir des clés anglaises dans le fichier source :

env.d.ts

declare namespace StarlightApp {
  type UIStrings = typeof import('./traductions').UIStrings.en;
  interface I18n extends UIStrings {}
}