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;
      injectTranslations: (Record<string, Record<string, string>>) => void;
    }) => void | Promise<void>;
  };
}

name

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

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

hooks.setup

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:

config

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.

updateConfig

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 config.social into the new social object:

plugin.ts

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

addIntegration

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:

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

      // Only add the React integration if it's not already loaded.
      if (!isReactLoaded) {
        addIntegration(react());
      }
    },
  },
};

astroConfig

type: AstroConfig

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

command

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

isRestart

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.

logger

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.

plugin.ts

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

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

[long-process-plugin] Starting long process…

injectTranslations

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

A callback function to add or update translation strings used in Starlight’s localization APIs.

In the following example, a plugin injects translations for a custom UI string named myPlugin.doThing for the en and fr locales:

plugin.ts

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

To use the injected translations in your plugin UI, follow the “Using UI translations” guide.

Types for a plugin’s injected translation strings are generated automatically in a user’s project, but are not yet available when working in your plugin’s codebase. To type the locals.t object in the context of your plugin, declare the following global namespaces in a TypeScript declaration file:

env.d.ts

declare namespace App {
  type StarlightLocals = import('@astrojs/starlight').StarlightLocals;
  // Define the `locals.t` object in the context of a plugin.
  interface Locals extends StarlightLocals {}
}

declare namespace StarlightApp {
  // Define the additional plugin translations in the `I18n` interface.
  interface I18n {
    'myPlugin.doThing': string;
  }
}

You can also infer the types for the StarlightApp.I18n interface from a source file if you have an object containing your translations.

For example, given the following source file:

ui-strings.ts

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

The following declaration would infer types from the English keys in the source file:

env.d.ts

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