30. Свои интеграции

Astro Integration API даёт вам полный контроль над процессом сборки. Вы можете создавать собственные плагины, которые ведут себя точно так же, как официальные интеграции.

Что такое Astro Integration API?

Интеграция — это объект с полем name и набором хуков жизненного цикла. Хуки — это функции, которые Astro вызывает на разных этапах: при запуске конфига, во время dev-сервера, при сборке.

export function myIntegration(options = {}) {
  return {
    name: 'my-integration',
    hooks: {
      'astro:config:setup': ({ updateConfig, injectScript }) => {
        // настройка конфига
      },
      'astro:build:done': ({ dir, pages }) => {
        console.log('Сборка завершена!', pages.length, 'страниц');
      },
    },
  };
}

Хуки жизненного цикла

Хуки настройки (Setup)

astro:config:setup — самый важный хук. Вызывается при инициализации. Доступны методы:

updateConfig(config) — изменение конфигурации Astro
addRenderer(renderer) — добавление рендерера (React, Vue)
injectScript(stage, content) — инжекция JS на страницы
injectRoute({ pattern, entrypoint }) — добавление маршрутов

astro:config:done — конфиг финализирован и заморожен, только для чтения.

Хуки dev-сервера

astro:server:setup — получаете объект Vite-сервера для расширения.

astro:server:start — сервер запущен, доступен адрес для подключения.

astro:server:done — сервер остановлен.

Хуки сборки (Build)

astro:build:start — сборка началась, можно очистить временные файлы.

astro:build:setup — можно изменить конфигурацию Vite для production.

astro:build:generated — статические страницы сгенерированы.

astro:build:ssr — SSR-манифест создан.

astro:build:done — сборка полностью завершена, получаете список страниц и маршрутов.

Создание простой интеграции

Добавим интеграцию, которая логирует время сборки:

export function buildTimer() {
  let startTime;

  return {
    name: 'build-timer',
    hooks: {
      'astro:build:start': () => {
        startTime = Date.now();
        console.log('⏱  Сборка началась...');
      },
      'astro:build:done': ({ pages }) => {
        const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
        console.log('✅ Готово! ' + pages.length + ' стр. за ' + elapsed + 'с');
      },
    },
  };
}

Добавление маршрутов программно

'astro:config:setup': ({ injectRoute }) => {
  injectRoute({
    pattern: '/robots.txt',
    entrypoint: './src/pages/robots.ts',
  });
}

Инжекция скриптов и стилей

'astro:config:setup': ({ injectScript }) => {
  // 'page-ssr' — в SSR-контексте
  // 'before-hydration' — до гидратации
  // 'page' — в конце <body>
  // 'head-inline' — в <head>
  injectScript('page', 'console.log("Hello from integration!");');
}

Vite-плагин внутри интеграции

'astro:config:setup': ({ updateConfig }) => {
  updateConfig({
    vite: {
      plugins: [myVitePlugin()],
    },
  });
}

Публикация на npm

Структура пакета для публикации:

my-astro-integration/
├── src/
│   └── index.ts       ← основной файл интеграции
├── package.json
└── README.md

В package.json обязательно укажите keywords: ["astro-integration"] — это позволит найти ваш пакет на astro.build/integrations.