Pular para o conteúdo

Referência de plugins

Os plugins do Starlight podem personalizar a configuração, UI, e comportamento, além de serem fáceis de compartilhar e reutilizar. Essa página de referência documenta a API que os plugins tem acesso.

Aprenda mais sobre como usar um plugin do Starlight na Referência da Configuração.

Referência rápida da API

Um plugin do Starlight segue o seguinte formato. Veja abaixo os detalhes das diferentes propriedades e parâmetros de 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;
}) => void | Promise<void>;
};
}

name

tipo: string

Um plugin deve fornecer um nome único que o descreve. O nome é usado nas mensagens de log relacionadas ao plugin e pode ser utilizado por outros plugins para detectar a sua presença.

hooks

Hooks são funções que o Starlight chama para executar um código do plugin em momentos específicos. Atualmente, o Starlight suporta apenas o hook setup.

hooks.setup

Função de setup chamada quando o Starlight é iniciado (durante a execução do hook de integração astro:config:setup). O hook setup pode ser utilizado para atualizar a configuração do Starlight ou adicionar integrações ao Astro.

Este hook é chamado com as seguintes opções:

config

tipo: StarlightUserConfig

Uma cópia somente leitura da configuração do Starlight fornecida pelo usuário. Essa configuração pode ter sido atualizada por outros plugins configurados antes desse.

updateConfig

tipo: (newConfig: StarlightUserConfig) => void

Uma função de callback para atualizar a configuração do Starlight fornecida pelo usuário. Forneça as chaves de configuração no nível-raiz que você quer sobrescrever. Para atualizar valores de configuração aninhados, você precisa fornecer todo o objeto aninhado.

Para estender uma configuração existente sem sobrescrevê-la, espalhe os valores existentes no novo valor. No seguinte exemplo, uma nova conta de mídia social é adicionada à configuração existente espalhando o objeto config.social no novo 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

Uma função de callback para adicionar uma Integração Astro requerida pelo plugin.

No seguinte exemplo, o plugin primeiro verifica se a Integração de React do Astro está configurada, caso não esteja, usa addIntegration() para adicioná-la:

plugin.ts
import react from '@astrojs/react';
export default {
name: 'plugin-using-react',
hooks: {
plugin({ addIntegration, astroConfig }) {
const isReactLoaded = astroConfig.integrations.find(
({ name }) => name === '@astrojs/react'
);
// Só adiciona a integração com o React se ela não estiver carregada.
if (!isReactLoaded) {
addIntegration(react());
}
},
},
};

astroConfig

tipo: AstroConfig

Uma cópia somente leitura da configuração do Astro fornecida pelo usuário.

command

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

O comando usado para executar o Starlight:

  • dev - O projeto é executado com astro dev
  • build - O projeto é executado com astro build
  • preview - O projeto é executado com astro preview

isRestart

tipo: boolean

false quando o servidor de desenvolvimento é iniciado, true quando uma atualização é disparada. Razões comuns para um reinicio incluem um usuário editando o arquivo astro.config.mjs enquanto o servidor de desenvolvimento está sendo executado.

logger

tipo: AstroIntegrationLogger

Uma instância do Astro logger que você pode usar para escrever logs. Todas as mensagens de log serão prefixadas com o nome do plugin.

plugin.ts
export default {
name: 'long-process-plugin',
hooks: {
plugin({ logger }) {
logger.info('Iniciando um processo longo…');
// Algum processo longo…
},
},
};

O exemplo acima registrará um log que inclui a mensagem info fornecida:

Terminal window
[long-process-plugin] Iniciando um processo longo…