Skip to content

Plugins Reference

Starlight plugins can customize Starlight configuration, UI, and behavior, while also being easy to share and reuse. This reference page documents the API that plugins have access to.

Learn more about using a Starlight plugin in the Configuration Reference or visit the plugins showcase to see a list of available plugins.

Quick API Reference

A Starlight plugin has the following shape. See below for details of the different properties and hook parameters.

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>;


type: string

A plugin must provide a unique name that describes it. The name is used when logging messages related to this plugin and may be used by other plugins to detect the presence of this plugin.


Hooks are functions which Starlight calls to run plugin code at specific times. Currently, Starlight supports a single setup hook.


Plugin setup function called when Starlight is initialized (during the astro:config:setup integration hook). The setup hook can be used to update the Starlight configuration or add Astro integrations.

This hook is called with the following options:


type: StarlightUserConfig

A read-only copy of the user-supplied Starlight configuration. This configuration may have been updated by other plugins configured before the current one.


type: (newConfig: StarlightUserConfig) => void

A callback function to update the user-supplied Starlight configuration. Provide the root-level configuration keys you want to override. To update nested configuration values, you must provide the entire nested object.

To extend an existing config option without overriding it, spread the existing value into your new value. In the following example, a new social media account is added to the existing configuration by spreading into the new social object:

export default {
name: 'add-twitter-plugin',
hooks: {
setup({ config, updateConfig }) {
social: {,
twitter: '',


type: (integration: AstroIntegration) => void

A callback function to add an Astro integration required by the plugin.

In the following example, the plugin first checks if Astro’s React integration is configured and, if it isn’t, uses addIntegration() to add it:

import react from '@astrojs/react';
export default {
name: 'plugin-using-react',
hooks: {
setup({ addIntegration, astroConfig }) {
const isReactLoaded = astroConfig.integrations.find(
({ name }) => name === '@astrojs/react'
// Only add the React integration if it's not already loaded.
if (!isReactLoaded) {


type: AstroConfig

A read-only copy of the user-supplied Astro configuration.


type: 'dev' | 'build' | 'preview'

The command used to run Starlight:

  • dev - Project is executed with astro dev
  • build - Project is executed with astro build
  • preview - Project is executed with astro preview


type: boolean

false when the dev server starts, true when a reload is triggered. Common reasons for a restart include a user editing their astro.config.mjs while the dev server is running.


type: AstroIntegrationLogger

An instance of the Astro integration logger that you can use to write logs. All logged messages will be prefixed with the plugin name.

export default {
name: 'long-process-plugin',
hooks: {
setup({ logger }) {'Starting long process…');
// Some long process…

The example above will log a message that includes the provided info message:

Terminal window
[long-process-plugin] Starting long process…