Referencia de Plugins

Los plugins de Starlight pueden personalizar la configuración, la UI y el comportamiento, mientras que son fáciles de compartir y reutilizar. Esta página de referencia documenta la API a la que tienen acceso los plugins.

Aprende más sobre el uso de un plugin de Starlight en la Referencia de Configuración o visita la exhibición de plugins para ver una lista de los plugins disponibles.

Referencia rápida de la API

Un plugin de Starlight tiene la siguiente forma. Consulta a continuación los detalles de las diferentes propiedades y parámetros del hook.

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;
    }) => void | Promise<void>;
  };
}

name

tipo: string

Un plugin debe proporcionar un nombre único que lo describa. El nombre se utiliza cuando se registran mensajes relacionados con este plugin y puede ser utilizado por otros plugins para detectar la presencia de este plugin.

hooks

Los hooks son funciones que Starlight llama para ejecutar código de plugin en momentos específicos. Actualmente, Starlight admite un único hook setup.

hooks.setup

La función de configuración es llamada cuando se inicializa Starlight (durante el hook de integración astro:config:setup).

El hook setup se puede utilizar para actualizar la configuración de Starlight o añadir integraciones de Astro.

Este hook es llamado con las siguientes opciones:

config

tipo: StarlightUserConfig

Una copia de lectura de la configuración de Starlight proporcionada por el usuario. Esta configuración puede haber sido actualizada por otros plugins configurados antes del actual.

updateConfig

tipo: (newConfig: StarlightUserConfig) => void

Una función callback para actualizar la configuración de Starlight. Proporciona las claves de configuración de nivel raíz que deseas sobreescribir. Para actualizar los valores de configuración anidados, debes proporcionar el objeto anidado completo.

Para extender una opción de configuración existente sin sobreescribirla, extiende el valor existente en tu nuevo valor. En el siguiente ejemplo, se agrega una nueva cuenta en social a la configuración existente extendiendo ‘config.social’ en el nuevo objeto social:

plugin.ts

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

addIntegration

tipo: (integration: AstroIntegration) => void

Una función callback para añadir una integración de Astro requerida por el plugin.

En el siguiente ejemplo, el plugin primero comprueba si la integración de React de Astro está configurada y, si no lo está, utiliza addIntegration() para añadirla:

plugin.ts

import react from '@astrojs/react';

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

      // Solo agrega la integración de React si aún no está cargada.
      if (!isReactLoaded) {
        addIntegration(react());
      }
    },
  },
};

astroConfig

tipo: AstroConfig

Una copia de lectura de la configuración de Astro proporcionada por el usuario.

command

tipo: 'dev' | 'build' | 'preview'

El comando usado para ejecutar Starlight:

• dev - El proyecto se ejecuta con astro dev
• build - El proyecto se ejecuta con astro build
• preview - El proyecto se ejecuta con astro preview

isRestart

tipo: boolean

false cuando el servidor de desarrollo se inicia, true cuando se activa una recarga. Common reasons for a restart include a user editing their astro.config.mjs while the dev server is running.

logger

tipo: AstroIntegrationLogger

Una instancia del logger de integración de Astro que puedes utilizar para escribir logs. Todos los mensajes de registro se prefijarán con el nombre del plugin.

plugin.ts

export default {
  name: 'long-process-plugin',
  hooks: {
    setup({ logger }) {
      logger.info('Empezando un proceso largo…');
      // Algun proceso largo…
    },
  },
};

El ejemplo anterior registrará un mensaje que incluye el mensaje de información proporcionado:

[long-process-plugin] Empezando un proceso largo…

injectTranslations

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

Una función callback para añadir o actualizar las strings de traducción utilizadas en las APIs de localización de Starlight.

En el siguiente ejemplo, un plugin inyecta traducciones para una string de UI personalizada llamada myPlugin.doThing para los locales en y fr:

plugin.ts

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

Para usar las traducciones inyectadas en tu plugin de UI, sigue la guía “Usar traducciones de UI”.

Los tipos para las strings de traducción inyectadas en un plugin se generan automáticamente en el proyecto de un usuario, pero aún no están disponibles cuando trabajas en el código de tu plugin. Para tipar el objeto locals.t en el contexto de tu plugin, declara los siguientes espacios de nombres globales en un archivo de declaración de TypeScript:

env.d.ts

declare namespace App {
  type StarlightLocals = import('@astrojs/starlight').StarlightLocals;
  // Define el objeto `locals.t` en el contexto de un plugin.
  interface Locals extends StarlightLocals {}
}

declare namespace StarlightApp {
  // Define las traducciones adicionales del plugin en la interfaz `I18n`.
  interface I18n {
    'myPlugin.doThing': string;
  }
}

También puedes inferir los tipos para la interfaz StarlightApp.I18n a partir de un archivo fuente si tienes un objeto que contiene tus traducciones.

Por ejemplo, dado el siguiente archivo fuente:

ui-strings.ts

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

La siguiente declaración inferiría los tipos de las claves en inglés del archivo fuente:

env.d.ts

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